hecks 5.0.0 → 7.0.0

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

@@ -3,7 +3,7 @@
 require "rspec/core"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks run_spec_example`: runs one spec file filtered to one example
     # through `RSpec::Core::Runner`, so a `hecks quality_control bug.log --demonstration` string
     # needs no `-e` quoting.

data/lib/hecks/tools/stage_progress.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Tools
+    # Streams one line per check as the check starts and as it ends, so a long stage shows its
+    # progress before its verdict. Each line is written and flushed as it happens.
+    #
+    # Lines go to the real standard error by default, not to `$stderr`: a recorded run captures
+    # `$stderr` into its journal, and the progress would be swallowed there. The verdict stays on
+    # standard output, so a pipe still receives only the result.
+    class StageProgress
+      class << self
+        # Whether the lines are left out, as `-q` asks: set by the launcher for the length of a line.
+        # @return [Boolean]
+        attr_accessor :quiet
+      end
+      self.quiet = false
+
+      # @param io [#puts, #flush] where the lines are written; the process's own standard error
+      #   (file descriptor 2), whatever `$stderr` is redirected to at the time
+      def initialize(io = IO.new(2, "w", autoclose: false))
+        @io = io
+        @lock = Mutex.new
+      end
+
+      # @param id [String] the check's id
+      # @return [void] the line saying the check has started
+      def start(id)
+        line("start #{id}")
+      end
+
+      # @param id [String] the check's id
+      # @param passed [Boolean] whether the check exited 0
+      # @param seconds [Float] how long it ran
+      # @return [void] the line saying how the check ended
+      def finish(id, passed, seconds)
+        line("#{passed ? "ok" : "fail"} #{id} #{format("%.1fs", seconds)}")
+      end
+
+      private
+
+      # @param text [String] one line, written and flushed under a lock so threads do not interleave
+      # @return [void]
+      def line(text)
+        return if self.class.quiet
+
+        @lock.synchronize do
+          @io.puts(text)
+          @io.flush
+        end
+      end
+    end
+  end
+end

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

@@ -3,28 +3,28 @@
 require_relative "../../hecks"
 
 module Hecks
-  module CLI
+  module Tools
     # The command behind `hecks statements`: prints a booted domain's declared facts as plain
     # English sentences, through `Projections::Statements`.
     module Statements
-      USAGE = "usage: hecks statements <domain-path> <ChapterName>"
+      USAGE = "usage: hecks statements <domain-path> <BluebookName>"
 
       module_function
 
-      # Boots the domain and prints one sentence per declared fact of the named chapter.
+      # Boots the domain and prints one sentence per declared fact of the named bluebook.
       #
-      # @param argv [Array<String>] the domain path, then the chapter's name
+      # @param argv [Array<String>] the domain path, then the bluebook's name
       # @param cwd [String] what a relative domain path resolves against
       # @param out [IO] where the sentences go
       # @return [Integer] the exit status, 0 once printed
       # @raise [SystemExit] with the usage line when an argument is missing
       def call(argv, cwd: Dir.pwd, out: $stdout)
-        domain_path, chapter_name = argv
-        abort USAGE unless domain_path && chapter_name
+        domain_path, declaration_name = argv
+        abort USAGE unless domain_path && declaration_name
 
         runtime = Hecks.boot(File.expand_path(domain_path, cwd))
-        chapter = runtime.registry.bluebook(chapter_name)
-        Hecks::Projector.call(:statements, bluebook: chapter).each { |statement| out.puts statement }
+        declaration = runtime.bluebook(declaration_name)
+        Hecks::Projector.call(:statements, bluebook: declaration).each { |statement| out.puts statement }
         0
       end
     end

data/lib/hecks/tools/stores.rb

@@ -0,0 +1,123 @@
+require "json"
+require_relative "../../hecks"
+require_relative "persistence_notice"
+
+module Hecks
+  module Tools
+    # The command behind `hecks stores`: every aggregate's current
+    # records as JSON (the head, not the journal — see `hecks history` for that).
+    module Stores
+      module_function
+
+      # Boots the domain `argv` names and prints its stores as one JSON document.
+      #
+      # @param argv [Array<String>] the domain directory, first
+      # @param program [String] the name the error message calls this command by
+      # @return [void]
+      # @raise [SystemExit] when `argv` is empty or the domain directory does not exist
+      def call(argv, program:)
+        domain = argv.first or abort "usage: #{program} <domain>"
+        unless Dir.exist?(domain)
+          warn "#{program}: no such domain #{domain.inspect}"
+          exit 1
+        end
+
+        registry = Hecks.boot(domain).registry
+        PersistenceNotice.announce(registry, program: program)
+        puts JSON.generate(stores_of(registry))
+      end
+
+      # @param registry [Runtime::Registry] a booted domain's registry
+      # @param only [String, nil] a storage name; the other aggregates' repositories are not read
+      # @return [Hash{String => Hash}] each aggregate's dump, keyed by its storage name
+      def stores_of(registry, only: nil)
+        registry.bluebooks.each_with_object({}) do |(name, bluebook), all|
+          bluebook.aggregates.each do |aggregate|
+            next if only && aggregate.storage_name != only
+
+            all[aggregate.storage_name] = data_for(registry.repository(name, aggregate))
+          end
+        end
+      end
+
+      # Reads what was asked for: reads only the named aggregate's repository when one is named.
+      #
+      # @param registry [Runtime::Registry] a booted domain's registry
+      # @param aggregate [String, nil] a storage name; nil reads every aggregate
+      # @param record [String, nil] a record id within `aggregate`
+      # @param flat [Boolean] unwrap the value objects (see `flatten`)
+      # @return [Hash] see `narrow`
+      # @raise [Runtime::NotFound] see `narrow`
+      def read(registry, aggregate, record, flat: false)
+        document = stores_of(registry, only: aggregate)
+        narrowed = narrow(document, aggregate, record, names: stored_names(registry))
+        flat ? flatten(narrowed) : narrowed
+      end
+
+      # Unwraps every value object (`{ "value" => x }`) to `x`, at any depth, so a record reads as
+      # `status: "concluded"` and not `status: { value: "concluded" }`. A hash with any other key
+      # is kept as it is, with its own values unwrapped.
+      #
+      # @param node [Object] a hash, an array or a scalar from a stores document
+      # @return [Object] the same shape with each single-`value` hash replaced by its value
+      def flatten(node)
+        case node
+        when Hash then node.keys == ["value"] ? flatten(node["value"]) : node.transform_values { |inner| flatten(inner) }
+        when Array then node.map { |inner| flatten(inner) }
+        else node
+        end
+      end
+
+      # Narrows the whole document to what was asked for: all of it, one aggregate's dump, or
+      # one record of an aggregate as its plain fields.
+      #
+      # @param document [Hash{String => Hash}] `stores_of`'s answer
+      # @param aggregate [String, nil] a storage name from the document; nil keeps everything
+      # @param record [String, nil] a record id within `aggregate`; nil keeps its whole dump
+      # @param names [Array<String>] the storage names to list when `aggregate` is not stored
+      # @return [Hash] the whole document, `{ aggregate => dump }`, or the one record's fields
+      # @raise [Runtime::NotFound] when the aggregate is not stored, the record is not in it, or a
+      #   record is named without an aggregate
+      def narrow(document, aggregate, record, names: document.keys)
+        raise Runtime::NotFound, "name the aggregate the record is in" if record && !aggregate
+        return document unless aggregate
+
+        dump = document.fetch(aggregate) do
+          raise Runtime::NotFound, "no aggregate stored as #{aggregate.inspect}; stored: #{names.join(", ")}"
+        end
+        record ? one_record(dump, aggregate, record) : { aggregate => dump }
+      end
+
+      # The storage names a booted domain keeps records under, read without reading any record.
+      #
+      # @param registry [Runtime::Registry] a booted domain's registry
+      # @return [Array<String>] one storage name per aggregate
+      def stored_names(registry)
+        registry.bluebooks.values.flat_map { |bluebook| bluebook.aggregates.map(&:storage_name) }
+      end
+
+      # @api private
+      def one_record(dump, aggregate, record)
+        dump.fetch("authoritative").find { |row| row["id"] == record } or
+          raise Runtime::NotFound, "no #{aggregate} record with id #{record.inspect}"
+      end
+
+      # Reads one aggregate's current records as plain JSON-ready hashes, ordered by id.
+      #
+      # @param repository [Ports::Persistence::AppendOnly] the aggregate's repository
+      # @return [Array<Hash{String => Object}>] one hash per stored `Runtime::Instance`,
+      #   sorted by id; `[]` when the aggregate has no records
+      def records(repository)
+        repository.all.sort_by(&:id).map { |instance| JSON.parse(JSON.generate(instance.to_h)) }
+      end
+
+      # Shapes one aggregate's dump for the top-level stores document.
+      #
+      # @param repository [Ports::Persistence::AppendOnly] the aggregate's repository
+      # @return [Hash{String => Object}] `"authoritative"` mapped to `records(repository)`
+      def data_for(repository)
+        { "authoritative" => records(repository) }
+      end
+    end
+  end
+end

data/lib/hecks/{cli → tools}/stress_concurrency_specs/reporting.rb

@@ -1,11 +1,14 @@
 require "fileutils"
 
 module Hecks
-  module CLI
+  module Tools
     module StressConcurrencySpecs
       # The verdict of a stress run: the clean line, or each failing run's saved log and how to
       # reproduce it. `StressConcurrencySpecs` extends it.
       module Reporting
+        # A parenthesis, which a saved log's file name leaves out.
+        PARENTHESIS = /[()]/
+
         # @param root [String] the checkout; failing runs' output is saved under its `tmp/`
         # @param results [Array<Hash>] every run's result
         # @param out [IO] where the verdict goes
@@ -33,7 +36,7 @@ module Hecks
         def save_failure(root, failure, out)
           dir = File.join(root, "tmp/stress-failures")
           FileUtils.mkdir_p(dir)
-          path = File.join(dir, "#{failure[:label].tr(" ", "_").gsub(/[()]/, "")}-seed#{failure[:seed]}.log")
+          path = File.join(dir, "#{failure[:label].tr(" ", "_").gsub(PARENTHESIS, "")}-seed#{failure[:seed]}.log")
           File.write(path, failure[:output])
           out.puts "  [#{failure[:label]}] seed #{failure[:seed]} — output saved to #{path.sub("#{root}/", "")}"
           out.puts "    reproduce: #{failure[:reproduce]}"

data/lib/hecks/{cli → tools}/stress_concurrency_specs/usage.rb

@@ -1,8 +1,8 @@
 module Hecks
-  module CLI
+  module Tools
     module StressConcurrencySpecs
       USAGE = <<~TEXT.freeze
-        Usage: hecks stress_concurrency [--runs N] [--parallel N] [--seed-start N]
+        Usage: hecks test_suite_run.stress_concurrency! [--runs N] [--parallel N] [--seed-start N]
 
           --runs N        How many times to run EACH group below. Each run uses
                            a different --seed (seed-start + run index).
@@ -16,8 +16,8 @@ module Hecks
           --seed-start N  First --seed value; runs use seed_start,
                            seed_start + 1, ... seed_start + runs - 1.
 
-        `hecks stress_concurrency` fills --runs and --seed-start from the defaults its
-        bluebook declares (`hecks stress_concurrency --help` shows them).
+        `hecks test_suite_run.stress_concurrency!` fills --runs and --seed-start from the defaults its
+        bluebook declares (`hecks test_suite_run.stress_concurrency! --help` shows them).
 
         Exits 0 if every run's every example passed, 1 if anything failed -
         failing runs' full output is saved under tmp/stress-failures/

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

@@ -7,8 +7,8 @@ require_relative "stress_concurrency_specs/usage"
 require_relative "stress_concurrency_specs/reporting"
 
 module Hecks
-  module CLI
-    # The command behind `hecks stress_concurrency`: reruns the thread-safety specs under many
+  module Tools
+    # The command behind `hecks test_suite_run.stress_concurrency!`: reruns the thread-safety specs under many
     # seeds, several OS processes at a time. A clean run shows only "not in this many tries", never
     # "impossible".
     #
@@ -65,7 +65,7 @@ module Hecks
         return false if missing.empty?
 
         warn "missing #{missing.map { |name| "--#{name.to_s.tr("_", "-")}" }.join(", ")}: " \
-             "`hecks stress_concurrency` supplies the defaults its bluebook declares (--help for usage)"
+             "`hecks test_suite_run.stress_concurrency!` supplies the defaults its bluebook declares (--help for usage)"
         true
       end
 

data/lib/hecks/tools/tail_merge.rb

@@ -63,13 +63,13 @@ module Hecks
         loading = Hecks::Ports::Loading.bootstrap
         directory = loading.bluebook_directory(domain_path)
         registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
-        load_chapters(loading, registry, directory)
-        bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
+        load_declarations(loading, registry, directory)
+        bluebook = registry.first_bluebook or abort "no bluebook in #{directory}"
         [registry, bluebook]
       end
 
       # Loads the library, the project and the domain into `registry`.
-      def load_chapters(loading, registry, directory)
+      def load_declarations(loading, registry, directory)
         Hecks.with_registry(registry) do
           loading.load_library
           loading.load_project(loading.shared_root(nil, directory))

data/lib/hecks/tools/tenant_provisioning.rb

@@ -4,6 +4,7 @@ require "hecks"
 # --adapter=PostgresEra needs the era persistence plugin (ADR 0033).
 require "hecks/ports/persistence/plugins/era"
 require "optparse"
+require "hecks/hecks/adapters/journal_store"
 require_relative "../tools"
 
 module Hecks
@@ -22,16 +23,16 @@ module Hecks
       USAGE = "usage: hecks deploy provision <domain-directory> <slug> --domain=NAME --realm=NAME " \
               "--schema=NAME --database=NAME [--adapter=PostgresEra]"
 
-      # The chapters that must boot together for a tenant to be declared and registered.
-      CHAPTER_FILES = %w[deploy/bluebook/deploy.bluebook deploy/bluebook/deploy.hecksagon
-                         tenancy/bluebook/tenancy.bluebook tenancy/bluebook/tenancy.hecksagon].freeze
+      # The bluebooks that must boot together for a tenant to be declared and registered.
+      BLUEBOOK_FILES = %w[deploy/bluebook/deploy.bluebook deploy/bluebook/deploy.hecksagon
+                          tenancy/bluebook/tenancy.bluebook tenancy/bluebook/tenancy.hecksagon].freeze
 
       module_function
 
       # Provisions the tenant and prints what it wrote and confirmed.
       #
       # @param argv [Array<String>] the domain directory, the tenant's slug, then the flags
-      # @param root [String] unused: the chapters are read from the library
+      # @param root [String] unused: the bluebooks are read from the library
       # @return [Integer] 0
       # @raise [SystemExit] with the reason on stderr when the shape is invalid, provisioning is
       #   refused, or the tenant never registers
@@ -76,15 +77,16 @@ module Hecks
       # @param slug [String] the tenant's slug
       # @param options [Hash] the parsed flags
       # @param domain_directory [String] the domain's directory
-      # @return [Hecks::Runtime::Dispatcher] the dispatcher both chapters share
+      # @return [Hecks::Runtime::Dispatcher] the dispatcher both bluebooks share
       # @raise [SystemExit] when the declared shape is refused, or provisioning is refused
       def provision(slug, options, domain_directory)
         lib_hecks  = File.expand_path("..", __dir__)
-        dispatcher = Hecks.boot_files(CHAPTER_FILES.map { |file| File.join(lib_hecks, file) }, install_driving: false)
+        dispatcher = Hecks.boot_files(BLUEBOOK_FILES.map { |file| File.join(lib_hecks, file) }, install_driving: false)
         provision_tenant(dispatcher, slug, tenant_facts(slug, options, domain_directory))
         refuse_if_refused(dispatcher, slug)
 
         puts "wrote #{File.join(domain_directory, "environments", "#{slug}.world")}"
+        hold_first_eras(domain_directory, slug)
         dispatcher
       end
 
@@ -139,6 +141,27 @@ module Hecks
         puts "#{options[:domain]} is tenant_capable? for #{slug.inspect} — registered under realm #{options[:realm].inspect}"
       end
 
+      # Holds era 1 of each era-keeping bluebook in the tenant's schema before the boot reads it:
+      # a boot only reads (ADR 0168), and `hold_first` is the one writer. A bluebook whose lineage
+      # already holds an era is left untouched, so a re-provision mints nothing and an existing
+      # schema's eras and rows are never read as new.
+      def hold_first_eras(domain_directory, slug)
+        held = Hecks::Adapters::JournalStore::HeldDomain.open(domain_directory, mode: :bare, environment: slug)
+        held.bluebook_names.each do |name|
+          domain = Hecks::Adapters::JournalStore::HeldDomain.new(held.registry, held.directory, name)
+          hold_first_era(domain) if domain.capable?
+        end
+      end
+
+      def hold_first_era(domain)
+        text = Hecks::Runtime::EraCheck.source_text_for(domain.bluebook, domain.directory, registry: domain.registry)
+        domain.writing do |lineage|
+          next if lineage.eras.any?
+
+          lineage.hold_first_era!(text, projection: domain.shape, aggregates: domain.aggregates, role: domain.app_role)
+        end
+      end
+
       # @raise [SystemExit] when a bluebook of the registry is not tenant capable
       def refuse_unless_tenant_capable(registry)
         registry.bluebooks.each_key do |name|

data/lib/hecks/tools/tools_doc.rb

@@ -7,7 +7,7 @@ require_relative "../tools"
 module Hecks
   module Tools
     # Writes the launcher forms of `docs/tools.md` from the `RetiredScript` rows of the Vocabulary
-    # chapter. Each row names a command (or, in QualityControl, a query); its form is rendered from
+    # bluebook. Each row names a command (or, in QualityControl, a query); its form is rendered from
     # that command's own arguments, the same projection the launcher parses against, so a form can
     # neither keep an argument the command dropped nor miss one it gained.
     #
@@ -73,7 +73,7 @@ module Hecks
       end
 
       # @param section [String] one of `SECTIONS`
-      # @param context [Context] the booted chapters
+      # @param context [Context] the booted bluebooks
       # @return [String] the section's table, header included
       def table(section, context)
         lines = rows.select { |row| row["section"] == section }.group_by { |row| row["script"] }.map do |script, group|
@@ -87,7 +87,7 @@ module Hecks
       def cell(row, context) = "`#{form(row, context).gsub("|", '\|')}`"
 
       # @param row [Hash{String => String}] a `RetiredScript` row
-      # @param context [Context] the booted chapters
+      # @param context [Context] the booted bluebooks
       # @return [String] the launcher form of the row's command or query
       def form(row, context)
         return row["form"] unless row["form"].to_s.empty?
@@ -164,7 +164,7 @@ module Hecks
 
         stale = SECTIONS.reject { |section| section_text(text, section) == section_text(fresh, section) }
         warn "tools_doc: #{DOCUMENT} differs from the RetiredScript rows in: #{stale.join(", ")} " \
-             "(run hecks regeneration_run.project_tools_doc --confirm)"
+             "(run hecks regeneration_run.project_tools_doc! --confirm)"
         1
       end
 
@@ -173,7 +173,7 @@ module Hecks
         text[/<!-- generated:begin tools section=#{section} -->\n(.*?)<!-- generated:end tools -->/m, 1]
       end
 
-      # The booted Hecks chapters the forms are rendered from, built once.
+      # The booted Hecks bluebooks the forms are rendered from, built once.
       class Context
         # @param root [String] the checkout
         def initialize(root)
@@ -183,13 +183,14 @@ module Hecks
 
         # @param row [Hash{String => String}] a `RetiredScript` row
         # @return [Array(Hash, Array<String>)] the projected command or query, and the words that
-        #   name it on the command line
+        #   name it on the command line, a command's with the bang the launcher requires
         # @raise [SystemExit] when the row names no command or query
         def spec_for(row)
-          chapter = %w[Custodian Codebase].include?(row["section"]) ? "Hecks" : row["section"]
+          declaration = %w[Custodian Codebase].include?(row["section"]) ? "Hecks" : row["section"]
           name = "#{Naming.snake(row["aggregate"])}.#{row["verb"]}"
-          spec = find_spec(projection(chapter), name) or abort "tools_doc: #{chapter} has no command or query #{name}"
-          [spec, words(chapter, name, row)]
+          cli = projection(declaration)
+          spec = find_spec(cli, name) or abort "tools_doc: #{declaration} has no command or query #{name}"
+          [spec, words(declaration, name, row, bang: cli[:names][:command].key?(name))]
         end
 
         private
@@ -199,27 +200,28 @@ module Hecks
           cli[:commands][cli[:names][:command][name]] || cli[:questions][cli[:names][:question][name]]
         end
 
-        def projection(chapter)
-          @projections[chapter] ||= begin
-            launcher = Adapters::Driving::LauncherOptions.settings(@runtime, chapter)
+        def projection(declaration)
+          @projections[declaration] ||= begin
+            launcher = Adapters::Driving::LauncherOptions.settings(@runtime, declaration)
             options = Adapters::Driving::LauncherOptions.projection(launcher, "hecks")
-            Projector.call(:cli, bluebook: @runtime.registry.bluebook(chapter), options: options)
+            Projector.call(:cli, bluebook: @runtime.bluebook(declaration), options: options)
           end
         end
 
-        # `hecks ir`, `hecks console`, `hecks quality_control sweep.run`, `hecks host.check_era`.
+        # `hecks ir`, `hecks console!`, `hecks quality_control sweep.run`, `hecks host.check_era!`.
         # The launcher takes a name that is only a query as a query, so no `query` word is needed.
-        def words(chapter, name, row)
-          route = route_for(Adapters::Driving::LauncherOptions.settings(@runtime, chapter) || {}, chapter, name, row)
-          return [route] if route
+        def words(declaration, name, row, bang:)
+          route = route_for(Adapters::Driving::LauncherOptions.settings(@runtime, declaration) || {}, declaration, name, row)
+          marked = ->(word) { bang ? "#{word}!" : word }
+          return [marked.call(route)] if route
 
-          [*(Naming.snake(chapter) unless chapter == "Hecks"), name]
+          [*(Naming.snake(declaration) unless declaration == "Hecks"), marked.call(name)]
         end
 
         # @return [String, nil] the one word the launcher routes the name by, when it has one
-        def route_for(settings, chapter, name, row)
+        def route_for(settings, declaration, name, row)
           route = (settings[:names] || {}).key(name)
-          route || (row["verb"] if chapter == "Hecks" && Array(settings[:legacy]).include?(row["verb"]))
+          route || (row["verb"] if declaration == "Hecks" && Array(settings[:legacy]).include?(row["verb"]))
         end
       end
     end

data/lib/hecks/tools/translation_audit/domain_loading.rb

@@ -13,8 +13,8 @@ module Hecks
           loading = Hecks::Ports::Loading.bootstrap
           directory = loading.bluebook_directory(domain_path)
           registry = Hecks::Runtime::Registry.new(root: File.dirname(directory))
-          load_chapters(registry, loading, directory)
-          bluebook = registry.bluebooks.values.first or abort "no bluebook in #{directory}"
+          load_declarations(registry, loading, directory)
+          bluebook = registry.first_bluebook or abort "no bluebook in #{directory}"
           [registry, bluebook, directory]
         end
 
@@ -35,7 +35,7 @@ module Hecks
 
         private
 
-        def load_chapters(registry, loading, directory)
+        def load_declarations(registry, loading, directory)
           Hecks.with_registry(registry) do
             loading.load_library
             loading.load_project(loading.shared_root(nil, directory))

data/lib/hecks/tools/translation_audit/edges.rb

@@ -11,16 +11,17 @@ module Hecks
         # The era the edge leads to and the chain of translations ending in it, or nil when the
         # journal stands at era 1 with nothing to audit.
         #
+        # @param directory [String, nil] the domain's bluebook directory, holding its implicit moves
         # @return [Array, nil] the era ordinal and the chain
-        def edge_chain(registry, bluebook, lineage)
+        def edge_chain(registry, bluebook, lineage, directory = nil)
           eras = lineage.eras
           current_shape = Hecks::Runtime::StorageShape.project(bluebook)
-          held_shape = Hecks::Runtime::StorageShape.project(lineage_manager.shadow(eras.last[:held_text]))
+          held_shape = lineage_manager.held_shape(eras.last)
 
           if held_shape == current_shape
             standing_chain(registry, bluebook, eras)
           else
-            pending_chain(registry, bluebook, lineage, eras)
+            pending_chain(registry, bluebook, lineage, eras, directory)
           end
         end
 
@@ -38,32 +39,36 @@ module Hecks
             puts "#{bluebook.name} stands at era 1 — no edge to audit."
             return nil
           end
-          [era, lineage_manager.edge_chain(registry, bluebook, eras, latest[:label])]
+          [era, lineage_manager.edge_chain(registry, bluebook, eras, latest[:label], target: latest)]
         end
 
         # The chain when the bluebook has moved past the held journal: audit the pending edge
         # before any mint.
-        def pending_chain(registry, bluebook, lineage, eras)
+        def pending_chain(registry, bluebook, lineage, eras, directory)
           lineage_manager.ensure_named!(lineage, eras.last)
           latest = lineage.eras.last
-          pending = pending_translation(registry, bluebook, latest)
+          pending = pending_translation(registry, bluebook, latest, lineage, directory)
           chain = begin
-            lineage_manager.edge_chain(registry, bluebook, eras, latest[:label])
+            lineage_manager.edge_chain(registry, bluebook, eras, latest[:label], target: latest)
           rescue StandardError
             []
           end
           [latest[:ordinal] + 1, (chain || []) + [{ translation: pending }]]
         end
 
-        # @return [Object] the translation leading from `latest` to the bluebook
-        # @raise [SystemExit] when none is declared
-        def pending_translation(registry, bluebook, latest)
-          to_label = Hecks::Runtime::StorageShape.mint_hash(bluebook)[0, Hecks::Runtime::StorageShape::LABEL_LENGTH]
-          pending = registry.translations.find do |t|
-            t.domain == bluebook.name && t.from == latest[:label] && t.to == to_label
-          end
-          pending or abort "no translation edge leads #{latest[:label]} to #{to_label} — " \
-                           "run hecks scaffold_translation first"
+        # The edge the shared decision leads `latest` by, as a mint takes it.
+        #
+        # @return [Object] the edge leading from `latest` to the bluebook
+        # @raise [SystemExit] when the decision names no edge
+        def pending_translation(registry, bluebook, latest, lineage, directory)
+          verdict = lineage_manager::MintDecision.decide_latest(
+            latest, bluebook: bluebook, translations: registry.translations, directory: directory,
+            watermark: lineage.last_ordinal
+          )
+          return verdict.edge if verdict.verdict == "would_mint"
+
+          abort "no translation edge leads #{latest[:label]} to the current shape (the decision is " \
+                "#{verdict.verdict}) — run hecks scaffold_translation first"
         end
       end
     end

data/lib/hecks/tools/translation_audit/verdicts.rb

@@ -50,7 +50,7 @@ module Hecks
         end
 
         def records_before(lineage, aggregate, era, chain)
-          return lineage.translated_latest(aggregate, era, chain[0..-2]) if chain.size > 1
+          return lineage.received_latest(aggregate, era, chain) if chain.size > 1
 
           lineage.ancestor_latest(aggregate, era, chain)
         end

data/lib/hecks/tools/translation_audit.rb

@@ -17,7 +17,18 @@ module Hecks
     #   hecks audit_translation <domain>
     module TranslationAudit
       # What one audit run works on: the loaded domain and its open journal.
-      Session = Struct.new(:registry, :bluebook, :directory, :db, :lineage)
+      Session = Struct.new(:registry, :bluebook, :directory, :db, :lineage) do
+        # @return [Boolean] whether the journal holds no era yet
+        def no_era? = lineage.eras.empty?
+
+        # @return [String] the name of the bluebook being audited
+        def bluebook_name = bluebook.name
+
+        # Closes the journal's database.
+        #
+        # @return [void]
+        def close = db.close
+      end
 
       extend DomainLoading
       extend Edges
@@ -43,9 +54,9 @@ module Hecks
       # @param session [Session] the loaded domain and its open journal
       # @return [Integer] the exit status
       def audit(session)
-        return hold_first_era(session) if session.lineage.eras.empty?
+        return hold_first_era(session) if session.no_era?
 
-        audit_edge(session, edge_chain(session.registry, session.bluebook, session.lineage))
+        audit_edge(session, edge_chain(session.registry, session.bluebook, session.lineage, session.directory))
       end
 
       # @param found [Array, nil] the era ordinal and the chain of translations ending in it, or nil
@@ -66,8 +77,8 @@ module Hecks
       def hold_first_era(session)
         session.lineage.hold_first!(Hecks::Runtime::EraCheck.source_text_for(session.bluebook, session.directory),
                                     projection: Hecks::Runtime::StorageShape.project(session.bluebook))
-        puts "#{session.bluebook.name} held era 1 just now — no edge to audit."
-        session.db.close
+        puts "#{session.bluebook_name} held era 1 just now — no edge to audit."
+        session.close
         0
       end
     end

data/lib/hecks/tools/translation_scaffold/reporting.rb

@@ -7,10 +7,13 @@ module Hecks
     module TranslationScaffold
       # Says what the written edge file leaves to decide.
       module Reporting
+        # An `unresolved` line the scaffold leaves for a person to decide.
+        UNRESOLVED_LINE = /^\s*unresolved /
+
         # @return [void]
         def report(path, diffed)
           text = File.read(path)
-          unresolved = text.scan(/^\s*unresolved /).size
+          unresolved = text.scan(UNRESOLVED_LINE).size
           unclaimed = diffed ? diffed[:unclaimed] : []
           puts "wrote #{path}"
           unclaimed.each { |name| puts unclaimed_message(name) }