hecks 6.0.0 → 7.0.0

data/lib/hecks/hecks/adapters/git_rehearsal/stages.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "../shell"
+require "hecks/vendoring/git_environment"
+require "hecks/vocabulary"
+require_relative "impacted"
+
+module Hecks
+  module Adapters
+    class GitRehearsal
+      # The stages a rehearsal runs, run in a copy of the commit. Which ones is data: the
+      # `RehearsalScope` row of the scope lists `RehearsalStage` rows of the Vocabulary bluebook
+      # (the gate's `quick` stage, the specs the
+      # push's changes touch), and this only runs them. Nothing here runs the full spec suite.
+      class Stages
+        # How one stage ended.
+        #
+        # @!attribute [r] name
+        #   @return [String] the stage
+        # @!attribute [r] passed
+        #   @return [Boolean] whether it passed
+        # @!attribute [r] detail
+        #   @return [String] what failed, naming the check and the spec; empty when it passed
+        Result = Struct.new(:name, :passed, :detail) do
+          # @return [String] the stage, pass or fail, and what failed
+          def line = passed ? "#{name}: pass#{detail}" : "#{name}: FAIL #{detail}"
+        end
+
+        # The gate script, as the pre-push hook calls it.
+        GATE = ["bundle", "exec", "ruby", "-Ilib", "-e", 'require "hecks/tools"; Hecks::Tools.script("gate", ARGV)'].freeze
+
+        # The gate's red verdict line: `[gate quick] red: shape_ledger, rubocop`.
+        RED = /^\[gate \S+\] red: ([^;\n]+)/
+
+        # A failing example as rspec prints it in its summary: `rspec ./spec/a_spec.rb:12 # ...`.
+        FAILED_SPEC = %r{^rspec (\./\S+)}
+
+        # The variables of the calling process that would point a copy's `bundle exec` at the
+        # checkout the rehearsal was asked from.
+        BUNDLER = %w[BUNDLE_GEMFILE BUNDLE_BIN_PATH RUBYOPT RUBYLIB].freeze
+
+        # @param directory [String] the copy of the commit the stages run in
+        # @param branch [String] the branch pushed; impacted specs compare with `origin/<branch>`
+        # @param impacted_limit [Integer, nil] the most impacted spec files to run
+        # @param impacted_width [Integer, nil] how many of them run at once
+        # @param scope [String] a `RehearsalScope` row: `quick` or `deep`
+        def initialize(directory, branch: "main", impacted_limit: nil, impacted_width: nil, scope: "quick")
+          @scope = scope
+          @directory = directory
+          @branch = branch
+          @impacted_limit = impacted_limit
+          @impacted_width = impacted_width
+          @shell = Shell.new
+        end
+
+        # @return [Array<Result>] each stage's result, in the order the scope's row lists them
+        def run = self.class.rows(@scope).map { |row| step(row) }
+
+        # @param scope [String] a scope's name
+        # @return [Array<Hash>] the scope's `RehearsalStage` rows, in the order it runs them
+        # @raise [KeyError] when no `RehearsalScope` row has that name
+        def self.rows(scope)
+          stages = Vocabulary.rows("RehearsalStage").to_h { |row| [row["name"], row] }
+          scope_row = Vocabulary.rows("RehearsalScope").find { |row| row["name"] == scope }
+          raise KeyError, "no rehearsal scope #{scope.inspect}" unless scope_row
+
+          scope_row["stages"].split(",").map { |name| stages.fetch(name) }
+        end
+
+        # @return [Array<String>] the names of the rehearsal scopes
+        def self.scopes = Vocabulary.rows("RehearsalScope").map { |row| row["name"] }
+
+        private
+
+        def step(row)
+          case row["kind"]
+          when "gate" then gate(row["argument"])
+          else impacted
+          end
+        end
+
+        def gate(stage)
+          result = capture(*GATE, stage, env: { "HECKS_ENVIRONMENT" => "memory" })
+          return Result.new(stage, true, "") if result.ok?
+
+          Result.new(stage, false, failure(result, checks: result.out[RED, 1]))
+        end
+
+        def failure(result, checks: nil)
+          specs = failing_specs(result)
+          parts = []
+          parts << "failing check: #{checks.strip}" if checks
+          parts << "failing spec: #{specs.join(", ")}" unless specs.empty?
+          parts << "exit #{result.exit_code}: #{last_line(result)}" if parts.empty?
+          parts.join("; ")
+        end
+
+        def failing_specs(result) = spec_names(result.out)
+
+        def spec_names(output) = output.scan(FAILED_SPEC).flatten.uniq
+
+        def last_line(result) = printed_lines(result).last.to_s
+
+        def printed_lines(result) = "#{result.out}#{result.err}".lines.map(&:strip).reject(&:empty?)
+
+        def impacted
+          runner = ->(directory, *command, env:) { capture(*command, env: env, directory: directory) }
+          Impacted.build(@directory, branch: @branch, capture: runner, limit: @impacted_limit, width: @impacted_width).result
+        end
+
+        def capture(*command, env:, directory: @directory)
+          clean = BUNDLER.to_h { |name| [name, nil] }.merge(Vendoring::GitEnvironment.clean).merge(env)
+          @shell.capture(*command, env: clean, chdir: directory)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_rehearsal.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/git_rehearsal"
+
+Hecks.adapter "GitRehearsal" do
+  port "Rehearsing"
+end

data/lib/hecks/hecks/adapters/git_rehearsal.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "git"
+require_relative "console_capture"
+require_relative "git_rehearsal/reading"
+require_relative "git_rehearsal/bench"
+require_relative "git_rehearsal/stages"
+require_relative "git_rehearsal/record"
+require_relative "git_rehearsal/due"
+require_relative "git_rehearsal/line"
+
+module Hecks
+  module Adapters
+    # The `Rehearsing` port's adapter for `PushRehearsal`: runs, against local `main` and without
+    # pushing, the stages of a scope, and reports whether a push is due.
+    #
+    # A scope is a `RehearsalScope` row of the Vocabulary bluebook: `quick` (the gate's quick
+    # stage, the push gate; a landing asks) or `deep` (quick plus the impacted specs; opt-in). Quick
+    # has its own line, record and bench, so it runs alongside a deep one. A rehearsal checks out a
+    # detached copy of `main`, runs the scope's stages in it and removes it. It pushes nothing and
+    # writes only a one-line record in the common git directory, which the `Due` query reads back.
+    class GitRehearsal
+      include Reading
+
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] `impacted_spec_limit:` the most impacted spec files run (60);
+      #   `impacted_spec_width:` how many run at once (2)
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @git = Git.new
+        @impacted_limit = settings[:impacted_spec_limit]
+        @impacted_width = settings[:impacted_spec_width]
+      end
+
+      # Rehearses the push of a branch, one at a time per repository and scope.
+      #
+      # A land that arrives while one runs marks `pending: rehearse <sha>` and is refused with that
+      # sentence; the running rehearsal then runs once more for the latest commit, however many
+      # landed. Benches a killed rehearsal left registered are removed first.
+      #
+      # @param held [Hash] the `PushRehearsal` record: `checkout`, `branch` (`main` by default) and
+      #   `scope` (a `RehearsalScope` row: `quick` by default, or `deep`)
+      # @return [Hash{Symbol => Hash}] `outcome:` (`green` or `red`), `rehearsed:` the commit,
+      #   `report:` one line per stage saying pass or fail
+      # @raise [ConsoleCapture::Failure] when the checkout is not a repository, has no such branch,
+      #   or another rehearsal is running
+      def trial(**held)
+        @checkout = primary(plain(held[:checkout]) || Dir.pwd)
+        branch = plain(held[:branch]) || "main"
+        @scope = scope_of(plain(held[:scope]))
+        in_line(branch, head(branch))
+      end
+
+      # Says whether a push is due, from what git already holds: nothing is fetched or pushed.
+      #
+      # @param held [Hash] `checkout` (a directory inside the repository)
+      # @return [Hash{Symbol => String}] `text:` the commits ahead, the oldest one's age and the
+      #   last rehearsal's result
+      # @raise [ConsoleCapture::Failure] when the checkout is not a repository
+      def due(**held)
+        @checkout = primary(plain(held[:checkout]) || Dir.pwd)
+        { text: Due.new(@git, @checkout).report }
+      end
+
+      private
+
+      # Rehearses in the repository's line: at once when none runs, else marks the commit pending
+      # and
+      # tries the line once more in case the running rehearsal ended meanwhile.
+      def in_line(branch, commit)
+        answer = queue.running { drain(branch, commit) }
+        return answer unless answer == :busy
+
+        pending = queue.mark(branch, commit)
+        answer = queue.running { drain(branch, queue.take && head(branch)) }
+        answer.is_a?(Hash) ? answer : pending!(pending, branch)
+      end
+
+      def pending!(pending, branch)
+        raise ConsoleCapture::Failure,
+              "#{pending}: a rehearsal is already running in this repository and will run once more for the latest #{branch}"
+      end
+
+      def queue = Line.new(@git, @checkout, scope: @scope)
+
+      def scope_of(scope)
+        return scope || "quick" if scope.nil? || Stages.scopes.include?(scope)
+
+        raise ConsoleCapture::Failure, "scope #{scope} is not a rehearsal scope: #{Stages.scopes.join(", ")}"
+      end
+
+      def head(branch) = read("rev-parse", "--verify", "refs/heads/#{branch}^{commit}")
+
+      # Rehearses the commit, then once more for the latest of the branch for as long as a land has
+      # marked one pending; answers the last rehearsal.
+      def drain(branch, commit)
+        Bench.new(@git, @checkout, scope: @scope).sweep
+        answer = nil
+        while commit
+          answer = once(branch, commit)
+          again = queue.take
+          commit = again && head(again)
+          branch = again if again
+        end
+        answer
+      end
+
+      def once(branch, commit)
+        results = Bench.new(@git, @checkout, scope: @scope).rehearse(commit) { |directory| stages(directory, branch).run }
+        verdict = results.all?(&:passed) ? "green" : "red"
+        note = Record.new(@git, @checkout).write(commit, verdict, results, scope: @scope)
+        { outcome: { value: verdict }, rehearsed: { value: commit }, report: { value: report(branch, commit, results, note) } }
+      end
+
+      def report(branch, commit, results, note)
+        lines = [heading(branch, commit)] + results.map(&:line)
+        lines << note unless note == "recorded"
+        lines.join("\n")
+      end
+
+      def stages(directory, branch)
+        Stages.new(directory, branch: branch, impacted_limit: @impacted_limit,
+                    impacted_width: @impacted_width, scope: @scope)
+      end
+
+      def heading(branch, commit)
+        "#{@scope} rehearsal of #{branch} at #{short(commit)}; nothing was pushed"
+      end
+
+      # The repository's own checkout, found from any worktree of it.
+      def primary(directory)
+        raise ConsoleCapture::Failure, "#{directory} is not a directory" unless File.directory?(directory)
+
+        common = read("rev-parse", "--path-format=absolute", "--git-common-dir", dir: directory)
+        File.basename(common) == ".git" ? File.dirname(common) : common
+      end
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_train/bench.rb

@@ -7,9 +7,9 @@ require_relative "reading"
 module Hecks
   module Adapters
     class GitTrain
-      # A detached worktree a push is made from, removed once it ends. The local branch is checked
-      # out there and merged with the remote's when the two have parted, so the repository's
-      # pre-push hook checks the very commit that goes out, not whatever a checkout holds.
+      # A detached worktree a push is made from, removed once it ends. The boarded commit is checked
+      # out there and pushed by its own id, so the repository's pre-push hook checks the very commit
+      # that goes out, not whatever a checkout or a moving branch holds.
       class Bench
         include Reading
 
@@ -33,12 +33,13 @@ module Hecks
           @config = config
         end
 
-        # Pushes the local branch, merged with the remote's when they have parted.
+        # Pushes one commit to the remote's branch, as it is.
         #
-        # @param local [String] the commit the local branch names
+        # @param local [String] the commit to push
         # @param tracking [String] the remote-tracking branch, just fetched
         # @return [String, Symbol] the commit pushed, or `:moved` when the remote's branch moved
-        # @raise [ConsoleCapture::Failure] when the two conflict, or the push is refused
+        # @raise [ConsoleCapture::Failure] when the commit is not built on the remote's branch, or
+        #   the push is refused
         def push(local, tracking)
           Dir.mktmpdir("hecks-push-train") do |scratch|
             bench = File.join(scratch, "bench")
@@ -52,21 +53,20 @@ module Hecks
         private
 
         def push_from(bench, local, tracking)
-          merge(bench, tracking) unless ancestor?(tracking, local)
-          pushed = @git.capture(*@config, "push", @remote, "HEAD:refs/heads/#{@branch}", chdir: bench)
-          return read("rev-parse", "HEAD", dir: bench) if pushed.ok?
+          diverged!(local, tracking) unless ancestor?(tracking, local)
+          carry = ["-c", "hecks.trainCarry=#{local}"]
+          pushed = @git.capture(*@config, *carry, "push", @remote, "#{local}:refs/heads/#{@branch}", chdir: bench)
+          return local if pushed.ok?
           return :moved if pushed.err.match?(MOVED)
 
           raise ConsoleCapture::Failure, "the push of #{@branch} was refused:\n#{tail(pushed)}"
         end
 
-        def merge(bench, tracking)
-          return if @git.capture("merge", "--no-edit", tracking, chdir: bench).ok?
-
-          conflicted = read("diff", "--name-only", "--diff-filter=U", dir: bench).split.join(", ")
-          @git.capture("merge", "--abort", chdir: bench)
+        # A commit not built on the remote's branch would need a merge, which would
+        # push a commit nobody minted for or settled: it is refused.
+        def diverged!(local, tracking)
           raise ConsoleCapture::Failure,
-                "#{@branch} and #{tracking} conflict in #{conflicted}: merge them by hand, then board again"
+                "#{tracking} moved since #{short(local)} was settled: it is not built on it; board again"
         end
 
         def tail(result) = "#{result.out}#{result.err}".lines.last(KEPT_LINES).join

data/lib/hecks/hecks/adapters/git_train/branch_guard.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "reading"
+
+module Hecks
+  module Adapters
+    class GitTrain
+      # What a boarding checks before it changes a checkout: that the branch still names the commit
+      # it expects, that the checkout has that branch checked out, and that nothing else is staged
+      # or modified to be swept into a commit.
+      class BranchGuard
+        include Reading
+
+        # @param git [Git] the adapter every git call goes through
+        # @param checkout [String] the repository's top level
+        # @param branch [String] the boarded branch
+        def initialize(git, checkout, branch)
+          @git = git
+          @checkout = checkout
+          @branch = branch
+        end
+
+        # @return [String] the commit the branch names
+        def head = read("rev-parse", "--verify", "refs/heads/#{@branch}^{commit}")
+
+        # @param expected [String] the commit the branch must still name
+        # @return [void]
+        # @raise [ConsoleCapture::Failure] when the branch names another commit
+        def unmoved!(expected)
+          now = head
+          return if now == expected
+
+          raise ConsoleCapture::Failure,
+                "#{@branch} moved since boarding (boarded #{short(expected)}, now #{short(now)}): board again"
+        end
+
+        # @return [void]
+        # @raise [ConsoleCapture::Failure] when the checkout's `HEAD` is not the boarded branch
+        def checked_out!
+          current = @git.capture("symbolic-ref", "--quiet", "HEAD", chdir: @checkout).out.strip
+          return if current == "refs/heads/#{@branch}"
+
+          raise ConsoleCapture::Failure,
+                "#{@checkout} has #{current.empty? ? "a detached HEAD" : current} checked out, not #{@branch}: " \
+                "changing it would change the wrong branch; board from a checkout of #{@branch}"
+        end
+
+        # @param except [Array<String>] paths the caller wrote itself, which may be modified
+        # @return [void]
+        # @raise [ConsoleCapture::Failure] when the branch is not checked out, or any tracked file
+        #   other than those paths is staged or modified
+        def clean!(except: [])
+          checked_out!
+          spec = except.map { |path| ":(exclude)#{path}" }
+          return if read("status", "--porcelain", "--untracked-files=no", "--", ".", *spec).empty?
+
+          raise ConsoleCapture::Failure, "#{@checkout} has staged or modified files; commit or discard them before boarding"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_train/carriage.rb

@@ -6,8 +6,12 @@ module Hecks
   module Adapters
     class GitTrain
       # One boarding's work once it holds the line: fetch the remote's branch, then either find
-      # the local branch already level with it or push the local branch, and ride again while
-      # commits landed during the push are still ahead.
+      # the boarded commit already on it or push exactly that commit.
+      #
+      # What is pushed is the commit the boarding named, never the local branch as it stands at push
+      # time: a branch that moved on since is refused by name (its new commits were not minted for
+      # or settled), and a remote that moved so the commit is not built on it is refused too.
+      # Commits that land during the push stay local and are named in the report.
       #
       # A push the remote turns away because its branch moved meanwhile (a push from another
       # machine, which the line does not hold back) is fetched again and retried.
@@ -17,9 +21,6 @@ module Hecks
         # How many times a push the remote turned away for having moved is tried.
         ATTEMPTS = 3
 
-        # How many pushes one boarding makes while the local branch keeps getting ahead.
-        RIDES = 3
-
         # @param git [Git] the adapter every git call goes through
         # @param checkout [String] the repository's top level
         # @param branch [String] the branch to push
@@ -37,49 +38,47 @@ module Hecks
         # @raise [ConsoleCapture::Failure] when there is no such branch
         def local_head = read("rev-parse", "--verify", "refs/heads/#{@branch}^{commit}")
 
-        # Carries the local branch: finds it already on the remote, or pushes it and pushes again
-        # while commits that landed meanwhile are still ahead (at most `RIDES` pushes).
+        # Carries one commit: finds it already on the remote, or pushes exactly it.
         #
-        # @param boarded [String] the commit the local branch named at boarding
+        # @param boarded [String] the commit to carry, which the local branch must still name
         # @return [Hash{Symbol => Hash}] the answer `GitTrain#carry` describes
-        # @raise [ConsoleCapture::Failure] when the branches conflict or the push is refused
+        # @raise [ConsoleCapture::Failure] when the branch moved since boarding, the remote's branch
+        #   moved so the commit is not built on it, or the push is refused
         def carry(boarded)
           fetch
-          return carried(boarded) if level?
+          moved_since!(boarded)
+          return carried(boarded) if ancestor?(boarded, tracking)
 
-          ride(boarded)
+          finish(push(boarded), boarded)
         end
 
         private
 
-        # Whether everything the local branch holds is on the remote.
-        def level? = ancestor?(local_head, tracking)
-
-        def ride(boarded, reports = [])
-          answer = push(boarded)
-          reports << answer.dig(:report, :value)
-          fetch
-          return finish(answer, reports) if level? || reports.size >= RIDES
+        # Refuses, pushing nothing, when the local branch names another commit than the boarded one.
+        def moved_since!(boarded)
+          now = local_head
+          return if now == boarded
 
-          ride(boarded, reports)
+          raise ConsoleCapture::Failure,
+                "#{@branch} moved since boarding (boarded #{short(boarded)}, now #{short(now)}): board again"
         end
 
-        def finish(answer, reports)
-          answer.merge(report: { value: (reports + leftover).join("; ") })
+        def finish(answer, boarded)
+          answer.merge(report: { value: [answer.dig(:report, :value), *leftover(boarded)].join("; ") })
         end
 
-        # What the local branch still holds that the remote lacks, named so nobody has to look.
-        def leftover
-          return [] if level?
+        # What the local branch holds beyond the commit carried, named so nobody has to look.
+        def leftover(boarded)
+          waiting = read("log", "--format=%h %s", "#{boarded}..#{@branch}").lines.map(&:strip)
+          return [] if waiting.empty?
 
-          waiting = read("log", "--format=%h %s", "#{tracking}..#{@branch}").lines.map(&:strip)
-          ["#{waiting.size} commit(s) still ahead of #{tracking}: #{waiting.first(5).join(" | ")}"]
+          ["#{waiting.size} commit(s) landed meanwhile and were not pushed (board again): #{waiting.first(5).join(" | ")}"]
         end
 
         def push(boarded, attempt = 1)
           before = read("rev-parse", tracking)
           pushed = Bench.new(@git, @checkout, branch: @branch, remote: @remote, config: @config)
-                        .push(local_head, tracking)
+                        .push(boarded, tracking)
           return retry_push(boarded, attempt) if pushed == :moved
 
           answer("pushed", boarded, pushed, pushed_report(before, pushed))

data/lib/hecks/hecks/adapters/git_train/launcher_shape.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "../journal_store/held_mint"
+require_relative "reading"
+
+module Hecks
+  module Adapters
+    class GitTrain
+      # The check that the mint is made for the shape being pushed.
+      #
+      # The mint reads the bluebooks of the code running the train (its launcher), not those of the
+      # repository being pushed. When both are checkouts of one repository, the launcher's `HEAD`
+      # must carry the same bluebooks, hecksagons, worlds and shape ledger as the boarded commit;
+      # if it does not, the boarding is refused with "the train is not at the boarded commit:
+      # refresh it first". A repository the launcher is not a checkout of, or one that holds no
+      # Hecks domain directory, has no launcher shape to compare and passes.
+      #
+      # The comparison is one `git diff --quiet` between the launcher's `HEAD` and the boarded
+      # commit, limited to the shape files of the Hecks domain directory: one git call.
+      class LauncherShape
+        include Reading
+
+        # The files of a domain directory that make up its shape.
+        SHAPE = %w[*.bluebook *.hecksagon *.world shapes.json].freeze
+
+        # @param git [Git] the adapter every git call goes through
+        # @param checkout [String] the repository's top level the boarding is for
+        # @param domain [String] the launcher's Hecks domain directory
+        def initialize(git, checkout, domain: JournalStore::HeldMint::DOMAIN)
+          @git = git
+          @checkout = checkout
+          @domain = domain
+        end
+
+        # @param boarded [String] the commit being boarded
+        # @return [void]
+        # @raise [ConsoleCapture::Failure] when the launcher's checkout is of the same repository
+        #   and its `HEAD` differs from the boarded commit in the shape files
+        def check!(boarded)
+          return unless File.directory?(@domain)
+
+          top = launcher_top
+          return unless top && same_repository?(top)
+
+          relative = File.realpath(@domain).delete_prefix("#{top}/")
+          launcher = read("rev-parse", "--verify", "HEAD^{commit}", dir: top)
+          return if same_shape?(launcher, boarded, relative)
+
+          raise ConsoleCapture::Failure,
+                "the train is not at the boarded commit: refresh it first (it runs #{short(launcher)}, " \
+                "the boarding is #{short(boarded)}, and their shape files in #{relative} differ)"
+        end
+
+        private
+
+        def same_shape?(launcher, boarded, relative)
+          paths = SHAPE.map { |name| ":(glob)#{relative}/**/#{name}" }
+          @git.capture("diff", "--quiet", launcher, boarded, "--", *paths, chdir: @checkout).ok?
+        end
+
+        def launcher_top
+          result = @git.capture("rev-parse", "--show-toplevel", chdir: @domain)
+          result.ok? ? File.realpath(result.out.strip) : nil
+        end
+
+        def same_repository?(top)
+          common = ->(dir) { @git.capture("rev-parse", "--path-format=absolute", "--git-common-dir", chdir: dir).out.strip }
+          File.realpath(common.call(top)) == File.realpath(common.call(@checkout))
+        rescue SystemCallError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/git_train/mint_step.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "../journal_store/held_mint"
+
+module Hecks
+  module Adapters
+    class GitTrain
+      # The step a boarding runs before it carries anything: the Hecks domain's held mint.
+      #
+      # It asks `JournalStore::HeldMint`, the mint entry point `Era.MintHeld` reaches, with all
+      # of its guards. A shape that did not move passes straight through, and so does a Hecks
+      # domain in Memory (the default, which holds no eras) or a world that declares
+      # `disposable_ledger true`, with no mint; a minted era is named in the
+      # report, and a refusal stops the boarding with the mint's own reason before anything is
+      # pushed.
+      class MintStep
+        # @param mint [#answer] answers `answer(run:, confirm:)` as `HeldMint#answer` does;
+        #   `HeldMint.new` when not given
+        def initialize(mint: nil)
+          @mint = mint || JournalStore::HeldMint.new
+        end
+
+        # Runs the mint for one boarding.
+        #
+        # @param run [String] the boarding's run key, which the mint is recorded under
+        # @param confirm [Boolean, nil] whether the boarding was confirmed
+        # @return [String] what the mint did, for the boarding's report
+        # @raise [Runtime::WiringError] naming the mint's refusal
+        def run(run:, confirm:)
+          answer = @mint.answer(run: run, confirm: confirm)
+          report(answer.dig(:outcome, :value), answer.dig(:label, :value))
+        rescue Runtime::WiringError => e
+          raise Runtime::WiringError, "the Hecks mint refused this boarding, so nothing was pushed: #{e.message}"
+        end
+
+        private
+
+        def report(outcome, label)
+          return "#{label} holds no eras, no mint needed" if outcome == "eraless"
+          return "the Hecks ledger is disposable, so no mint is needed" if outcome == "disposable"
+
+          outcome == "minted" ? "the Hecks mint minted #{label}" : "the Hecks shape #{label} did not move"
+        end
+      end
+    end
+  end
+end