hecks 3.5.0 → 3.7.0

data/lib/hecks/hecks/adapters/github_rulesets.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Hecks
+  module Adapters
+    # The rulesets of the repository `gh` is pointed at, read and written through `gh api`.
+    #
+    # `Tools::Lanes` projects each guarded `Lane` row into a ruleset and uses this to compare the
+    # projection with what GitHub holds, and to create or update it. Nothing here decides what a
+    # ruleset says; it only carries a ruleset to and from GitHub. `{owner}/{repo}` is a `gh api`
+    # template resolved from the git remote.
+    class GithubRulesets
+      # The part of a ruleset a lane projects: everything else GitHub fills in (ids, links,
+      # timestamps, defaults) is left out of a comparison.
+      COMPARED = %w[name target enforcement].freeze
+
+      # @param runner [#call, nil] runs `gh` with its arguments and stdin text, answering
+      #   `[stdout, stderr, success]`; the real `gh` when nil. A spec replaces it.
+      def initialize(runner: nil)
+        @runner = runner || method(:run_gh)
+      end
+
+      # @return [Array<Hash>] every ruleset of the repository, in full
+      # @raise [RuntimeError] when `gh` is missing or refuses
+      def all
+        listed = json(call("api", "repos/{owner}/{repo}/rulesets?per_page=100"))
+        listed.map { |ruleset| json(call("api", "repos/{owner}/{repo}/rulesets/#{ruleset.fetch("id")}")) }
+      end
+
+      # @param name [String] a ruleset's name
+      # @return [Hash, nil] the ruleset of that name, or nil when the repository has none
+      def named(name) = all.find { |ruleset| ruleset["name"] == name }
+
+      # Makes the ruleset exist as projected: creates it, or updates the one of that name.
+      #
+      # @param projected [Hash] the ruleset as `Tools::Lanes` projects it
+      # @return [Symbol] `:created` or `:updated`
+      # @raise [RuntimeError] when GitHub refuses it
+      def apply(projected)
+        live = named(projected.fetch("name"))
+        path = "repos/{owner}/{repo}/rulesets"
+        if live
+          call("api", "--method", "PUT", "#{path}/#{live.fetch("id")}", "--input", "-", stdin: JSON.generate(projected))
+          :updated
+        else
+          call("api", "--method", "POST", path, "--input", "-", stdin: JSON.generate(projected))
+          :created
+        end
+      end
+
+      # How a live ruleset differs from a projected one, over the parts a lane projects.
+      #
+      # @param projected [Hash] the ruleset as `Tools::Lanes` projects it
+      # @param live [Hash, nil] the ruleset GitHub holds, or nil when it has none
+      # @return [Array<String>] one line for each difference; empty when they agree
+      def differences(projected, live)
+        return ["#{projected["name"]}: GitHub has no such ruleset"] unless live
+
+        found = COMPARED.reject { |key| projected[key] == live[key] }.map do |key|
+          "#{projected["name"]}: #{key} is #{live[key].inspect} on GitHub, #{projected[key].inspect} in the model"
+        end
+        found + %i[compare_conditions compare_bypass compare_rules compare_checks].flat_map do |part|
+          send(part, projected, live)
+        end
+      end
+
+      private
+
+      def compare_conditions(projected, live)
+        mine = projected.dig("conditions", "ref_name", "include")
+        theirs = live.dig("conditions", "ref_name", "include")
+        mine == theirs ? [] : ["#{projected["name"]}: it guards #{theirs.inspect} on GitHub, #{mine.inspect} in the model"]
+      end
+
+      def compare_bypass(projected, live)
+        mine = actors(projected)
+        theirs = actors(live)
+        return [] if mine == theirs
+
+        ["#{projected["name"]}: bypass actors are #{theirs.inspect} on GitHub, #{mine.inspect} in the model"]
+      end
+
+      def compare_rules(projected, live)
+        mine = projected.fetch("rules").map { |rule| rule["type"] }.sort
+        theirs = live.fetch("rules", []).map { |rule| rule["type"] }.sort
+        mine == theirs ? [] : ["#{projected["name"]}: rules are #{theirs.inspect} on GitHub, #{mine.inspect} in the model"]
+      end
+
+      def compare_checks(projected, live)
+        mine = required(projected)
+        theirs = required(live)
+        return [] if mine == theirs
+
+        ["#{projected["name"]}: required checks are #{theirs.inspect} on GitHub, #{mine.inspect} in the model"]
+      end
+
+      # Each check a ruleset's `required_status_checks` rule demands, as its name and the app id it
+      # must come from (nil when any app may report it), sorted.
+      def required(ruleset)
+        rule = Array(ruleset["rules"]).find { |candidate| candidate["type"] == "required_status_checks" }
+        Array(rule&.dig("parameters", "required_status_checks"))
+          .map { |check| [check["context"], check["integration_id"]] }.sort_by(&:to_s)
+      end
+
+      def actors(ruleset)
+        Array(ruleset["bypass_actors"]).map { |actor| actor.values_at("actor_id", "actor_type", "bypass_mode") }.sort_by(&:to_s)
+      end
+
+      def call(*args, stdin: nil)
+        out, err, ok = @runner.call(args, stdin)
+        raise "gh #{args.first(3).join(" ")} failed: #{err.strip.empty? ? out.strip : err.strip}" unless ok
+
+        out
+      end
+
+      def json(text) = JSON.parse(text)
+
+      def run_gh(args, stdin)
+        out, err, status = Open3.capture3("gh", *args, stdin_data: stdin.to_s)
+        [out, err, status.success?]
+      rescue Errno::ENOENT
+        ["", "gh is not installed or not on PATH", false]
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/host_http.rb

@@ -28,11 +28,8 @@ module Hecks
       # @raise [ArgumentError] if the path or the secret is missing, or the scheme is unknown
       # @raise [ConsoleCapture::Failure] when any check failed
       def probe(**held)
-        options = %i[url path header scheme payload health_path state_path].to_h { |name| [name, plain(held[name])] }
-        options[:payload] ||= File.read(plain(held[:payload_file])) if plain(held[:payload_file])
-
         out = StringIO.new
-        status = CLI::SmokeHttp.new(CLI::SmokeHttp.resolve(options.compact, ENV), out: out).run
+        status = CLI::SmokeHttp.new(CLI::SmokeHttp.resolve(probe_options(held).compact, ENV), out: out).run
         raise ConsoleCapture::Failure, out.string.strip unless status.zero?
 
         { output: { value: out.string } }
@@ -50,8 +47,8 @@ module Hecks
       # @raise [Runtime::EraCheck::ExpectedEra::Unreachable] if the host cannot be reached
       # @raise [Runtime::EraCheck::ExpectedEra::BadResponse] if it answers no era
       def fetch(**held)
-        file = plain(held[:expected]) or raise ArgumentError, "no allow-list file to compare the era with"
-        timeout = plain(held[:timeout]) or raise ArgumentError, "no timeout to wait for the host with"
+        file = required(held[:expected], "no allow-list file to compare the era with")
+        timeout = required(held[:timeout], "no timeout to wait for the host with")
         finding = CLI::CheckEra.assess(plain(held[:host]), file, timeout: timeout.to_f)
 
         { era: { value: finding.verdict.era }, version: { value: finding.version },
@@ -60,6 +57,19 @@ module Hecks
 
       private
 
+      # The options the smoke check reads, from the record's fields; the payload file stands in
+      # for a payload that was not given.
+      def probe_options(held)
+        options = %i[url path header scheme payload health_path state_path].to_h { |name| [name, plain(held[name])] }
+        options[:payload] ||= File.read(plain(held[:payload_file])) if plain(held[:payload_file])
+        options
+      end
+
+      # The field's value, or an `ArgumentError` saying what is missing.
+      def required(argument, message)
+        plain(argument) or raise ArgumentError, message
+      end
+
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
     end
   end

data/lib/hecks/hecks/adapters/in_process_boot.rb

@@ -150,15 +150,19 @@ module Hecks
         steps ||= 30
         generated = Fuzzing::SequenceGenerator.generate(target, seed: seed, steps: steps,
                                                                 adversarial: adversarial || 0.0)
-        script = { name:  "#{File.basename(target)}-generated",
-                   note:  "generated by hecks generate_sequence: seed #{seed}, #{steps} steps " \
-                          "requested (#{generated.length} produced)",
-                   steps: generated }
-        report(JSON.pretty_generate(script))
+        report(JSON.pretty_generate(sequence_script(target, generated, seed, steps)))
       end
 
       private
 
+      # The replayable script for a generated sequence: its name, how it was made, its steps.
+      def sequence_script(target, generated, seed, steps)
+        { name:  "#{File.basename(target)}-generated",
+          note:  "generated by hecks generate_sequence: seed #{seed}, #{steps} steps " \
+                 "requested (#{generated.length} produced)",
+          steps: generated }
+      end
+
       # A value object arrives as `{ value: x }`; a bare argument is already plain.
       def plain(argument)
         argument.is_a?(Hash) ? argument[:value] : argument

data/lib/hecks/hecks/adapters/in_process_operations/tailing.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module InProcessOperations
+      # The loop behind `stream`: drains an event log past a cursor, then waits and drains again,
+      # until the block, a limit or a deadline ends it.
+      module Tailing
+        # Where a stream stands: log entries seen, entries handed over, whether a batch ended it.
+        Tail = Struct.new(:seen, :handed, :batch_done)
+
+        # What ends a stream and what it follows: the aggregate filter, the most entries to hand
+        # over, the monotonic time to give up at, and the seconds between checks.
+        Bounds = Struct.new(:aggregate, :cap, :deadline, :interval)
+
+        private
+
+        # The monotonic time `timeout` seconds from now, or nil when there is no timeout.
+        def deadline_for(timeout) = plain(timeout) && (monotonic + plain(timeout).to_f)
+
+        # Drains the log, then waits and drains again, until something ends the stream.
+        #
+        # @return [Integer] the count of log entries seen
+        def watch(repository, tail, bounds, &)
+          loop do
+            verdict = drain(repository, tail, bounds.aggregate, bounds.cap, &)
+            return tail.seen if verdict == :stop || tail.batch_done || expired?(bounds.deadline)
+
+            sleep((bounds.interval || 0.5).to_f)
+          end
+        end
+
+        # Whether the stream's deadline, when it has one, has passed.
+        def expired?(deadline) = deadline && monotonic >= deadline
+
+        # Hands over what the log holds past the tail, one entry at a time; answers `:stop` when the
+        # block or the limit ends the stream, so the tail's `seen` stays just past the last entry
+        # handed over.
+        def drain(repository, tail, filter, cap)
+          events = repository.events
+          while tail.seen < events.size
+            event = events[tail.seen]
+            tail.seen += 1
+            next unless followed?(event, filter)
+
+            return :stop if handed_over?(tail, yield(JSON.parse(JSON.generate(event.to_h))), cap)
+          end
+          nil
+        end
+
+        # Records that an entry was handed over, and whether its verdict or the limit ends the
+        # stream.
+        def handed_over?(tail, verdict, cap)
+          tail.handed += 1
+          tail.batch_done ||= verdict == :batch
+          verdict == :stop || (cap && tail.handed >= cap)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/in_process_operations.rb

@@ -3,6 +3,7 @@
 require "json"
 require "time"
 require_relative "console_capture"
+require_relative "in_process_operations/tailing"
 require "hecks/cli/run"
 require "hecks/cli/model_check"
 require "hecks/cli/smoke_test"
@@ -19,6 +20,8 @@ module Hecks
     # it printed. An answer records a success; a raise records a refusal, so a check that finds
     # something, or a run that fails, is refused with the report as its reason.
     module InProcessOperations
+      include Tailing
+
       # The chapters `hecks model_check` sweep when no domain is named need a
       # checkout; an installed gem has none.
       CHECKOUT_MARKER = "hecks.gemspec"
@@ -37,12 +40,7 @@ module Hecks
       #   domains it headed
       # @raise [ConsoleCapture::Failure] when a finding was left, or the analysis could not run
       def check(**held)
-        argv = plain(held[:domains]).to_s.split(",").map(&:strip).reject(&:empty?)
-        missing = argv.reject { |domain| File.exist?(domain) }
-        raise Runtime::NotFound, "no such domain #{missing.first.inspect}" if missing.any?
-
-        argv.unshift("--strict") if plain(held[:strict])
-        argv.unshift("--profile", plain(held[:profile]).to_s) if present?(held[:profile])
+        argv = check_argv(held)
 
         text = ConsoleCapture.answer do
           CLI::ModelCheck.call(argv, program: "hecks model_check", root: checkout_root)
@@ -97,6 +95,8 @@ module Hecks
         output(ConsoleCapture.answer { CLI::SmokeTest.call(argv, root: checkout_root || Dir.pwd) })
       end
 
+      # rubocop:disable Metrics/ParameterLists -- the keywords are the `Follow` query's declared arguments
+
       # A domain's event log past a cursor, answered once: what the stream yielded before it
       # ended. Pass the answered `cursor` back as `since` to keep tailing. `wait` bounds the stream
       # and it ends at the first entries, so a call returns as soon as there is something to say.
@@ -110,6 +110,7 @@ module Hecks
       # @return [Hash] the `Tail` row: `cursor:`, `events:` (payloads as JSON text) and `taken_at:`
       # @raise [Runtime::NotFound] if the domain cannot be found or keeps no event log
       def follow(domain:, aggregate: nil, since: nil, from_now: nil, wait: nil, interval: nil)
+        # rubocop:enable Metrics/ParameterLists
         registry = boot(domain).registry
         entries = []
         cursor = stream(domain: domain, aggregate: aggregate, since: since, from_now: from_now,
@@ -121,6 +122,8 @@ module Hecks
         { cursor: cursor, events: entries, taken_at: Time.at(Ports::Clock.now(registry)).utc.iso8601 }
       end
 
+      # rubocop:disable Metrics/ParameterLists -- the keywords are the caller-facing shape of a tail
+
       # Tails a domain's event log, handing each entry to the block as the log shows it, until
       # the block returns `:stop` (or `:batch`: after this check's entries), `limit` entries were
       # handed over, `timeout` seconds pass, or the reader goes away; unbounded, until interrupted.
@@ -134,43 +137,38 @@ module Hecks
       # @return [Integer] the count of log entries seen, to pass back as `since`
       # @raise [Runtime::NotFound] if the domain cannot be found or keeps no event log
       def stream(domain:, aggregate: nil, since: nil, from_now: nil, limit: nil, timeout: nil, interval: nil,
-                 registry: nil, &block)
+                 registry: nil, &)
+        # rubocop:enable Metrics/ParameterLists
         repository = event_repository(domain, registry)
         tail = Tail.new(plain(since)&.to_i || (plain(from_now) ? repository.events.size : 0), 0, false)
-        cap = plain(limit)&.to_i
-        deadline = plain(timeout) && (monotonic + plain(timeout).to_f)
-
-        loop do
-          verdict = drain(repository, tail, plain(aggregate), cap, &block)
-          return tail.seen if verdict == :stop || tail.batch_done || (deadline && monotonic >= deadline)
-
-          sleep((plain(interval) || 0.5).to_f)
-        end
+        bounds = Bounds.new(plain(aggregate), plain(limit)&.to_i, deadline_for(timeout), plain(interval))
+        watch(repository, tail, bounds, &)
       rescue Errno::EPIPE, Interrupt
         tail.seen
       end
 
       private
 
-      # Where a stream stands: log entries seen, entries handed over, whether a batch ended it.
-      Tail = Struct.new(:seen, :handed, :batch_done)
-
-      # Hands over what the log holds past the tail, one entry at a time; answers `:stop` when the
-      # block or the limit ends the stream, so the tail's `seen` stays just past the last entry
-      # handed over.
-      def drain(repository, tail, filter, cap)
-        events = repository.events
-        while tail.seen < events.size
-          event = events[tail.seen]
-          tail.seen += 1
-          next unless followed?(event, filter)
-
-          verdict = yield JSON.parse(JSON.generate(event.to_h))
-          tail.handed += 1
-          tail.batch_done ||= verdict == :batch
-          return :stop if verdict == :stop || (cap && tail.handed >= cap)
-        end
-        nil
+      # The words `hecks model_check` is run with: the named domains, behind `--strict` and
+      # `--profile` when asked for.
+      #
+      # @raise [Runtime::NotFound] if a named domain does not exist
+      def check_argv(held)
+        argv = named_domains(held)
+        argv.unshift("--strict") if plain(held[:strict])
+        argv.unshift("--profile", plain(held[:profile]).to_s) if present?(held[:profile])
+        argv
+      end
+
+      # The domain paths the record names, each of which must exist.
+      #
+      # @raise [Runtime::NotFound] if one does not
+      def named_domains(held)
+        argv = plain(held[:domains]).to_s.split(",").map(&:strip).reject(&:empty?)
+        missing = argv.reject { |domain| File.exist?(domain) }
+        raise Runtime::NotFound, "no such domain #{missing.first.inspect}" if missing.any?
+
+        argv
       end
 
       def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)

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

@@ -55,7 +55,7 @@ module Hecks
           diverged = domain.writing { |lineage| diverged_writes(domain, lineage) }
           PostgresEra::LineageManager.merge!(registry: domain.registry, bluebook: domain.bluebook,
                                              settings: domain.settings, winners: named)
-          ["#{domain.bluebook.name}: #{diverged} post-cut write#{'s' unless diverged == 1} in ancestor " \
+          ["#{domain.bluebook.name}: #{diverged} post-cut write#{"s" unless diverged == 1} in ancestor " \
            "eras before the merge",
            "merged — the head now interleaves both worlds by their recorded ordinals",
            *named.map { |id, side| "  winner #{id}=#{side} appended as the newest row" }].join("\n")
@@ -88,17 +88,19 @@ module Hecks
           before = missing.call
           return "#{domain.bluebook.name}: every held era already carries a projection — nothing to do." if before.zero?
 
-          begin
-            # Raises on the first row whose own digest check fails: a tampered row, not a merely
-            # legacy one, which backfilling must not paper over.
-            lineage.eras
-          rescue Runtime::WiringError => e
-            raise Runtime::WiringError, "#{domain.bluebook.name}: stopped at a row that isn't merely legacy — " \
-                                        "it fails its own integrity check: #{e.message} — resolve that first " \
-                                        "(`hecks reattest`), then run this again for the remaining rows."
-          end
+          require_legacy_rows!(domain, lineage)
           done = before - missing.call
-          "#{domain.bluebook.name}: backfilled #{done} era#{'s' unless done == 1} — every row now carries a projection."
+          "#{domain.bluebook.name}: backfilled #{done} era#{"s" unless done == 1} — every row now carries a projection."
+        end
+
+        # Raises on the first row whose own digest check fails: a tampered row, not a merely
+        # legacy one, which backfilling must not paper over.
+        def require_legacy_rows!(domain, lineage)
+          lineage.eras
+        rescue Runtime::WiringError => e
+          raise Runtime::WiringError, "#{domain.bluebook.name}: stopped at a row that isn't merely legacy — " \
+                                      "it fails its own integrity check: #{e.message} — resolve that first " \
+                                      "(`hecks reattest`), then run this again for the remaining rows."
         end
 
         def missing_projections(lineage)
@@ -120,13 +122,17 @@ module Hecks
         def apply_approve_translation(held)
           domain = HeldDomain.open(plain(held[:domain]))
           finding = domain.reading { |lineage| audited_edge(domain, lineage) }
-          document = Translation::ApprovalFile.build(
+          document = approval_document(domain, finding, held)
+          path = Translation::ApprovalFile.write!(domain.directory, finding.edge, document)
+          "approval of edge #{document["edge"]} written to #{path} (digest #{document["edge_digest"][0, 12]}…, " \
+            "by #{document["approved_by"]}). Commit it with the edge; the host applies it at its next boot."
+        end
+
+        def approval_document(domain, finding, held)
+          Translation::ApprovalFile.build(
             edge: finding.edge, approved_by: Git.new.identity(chdir: domain.directory),
             approved_at: Time.now.utc.iso8601, rehearsal: rehearsal_block(held)
           )
-          path = Translation::ApprovalFile.write!(domain.directory, finding.edge, document)
-          "approval of edge #{document['edge']} written to #{path} (digest #{document['edge_digest'][0, 12]}…, " \
-            "by #{document['approved_by']}). Commit it with the edge; the host applies it at its next boot."
         end
 
         def audited_edge(domain, lineage)

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

@@ -69,14 +69,23 @@ module Hecks
         # The shape not yet minted: the edge that leaves the latest era for the current shape.
         def pending(latest)
           label = Runtime::StorageShape.mint_hash(@held.bluebook)[0, Runtime::StorageShape::LABEL_LENGTH]
-          domain = @held.bluebook.name
-          leaving = @held.registry.translations.select { |t| t.domain == domain && t.from == latest[:label] }
-          edge = leaving.find { |t| t.to == label } or
+          leaving = leaving_edges(latest)
+          edge = edge_to(leaving, latest, label)
+          chain = @manager.edge_chain(@held.registry, @held.bluebook, @eras[0..-2] + [latest], label)
+          finding(chain, latest[:ordinal] + 1, leaving.size, edge)
+        end
+
+        # The leaving edge that arrives at the current shape.
+        def edge_to(leaving, latest, label)
+          leaving.find { |t| t.to == label } or
             raise Runtime::NotFound, "no translation edge leads #{latest[:label]} to #{label} — " \
                                      "run `hecks scaffold_translation` first"
-          ancestors = @eras[0..-2] + [latest]
-          chain = @manager.edge_chain(@held.registry, @held.bluebook, ancestors, label)
-          finding(chain, latest[:ordinal] + 1, leaving.size, edge)
+        end
+
+        # The registered translations that leave the latest era.
+        def leaving_edges(latest)
+          domain = @held.bluebook.name
+          @held.registry.translations.select { |t| t.domain == domain && t.from == latest[:label] }
         end
 
         def finding(chain, era, leaving, edge = chain.last[:translation])
@@ -109,14 +118,22 @@ module Hecks
         end
 
         def describe(aggregate, edge, verdict, records)
-          lines = ["── #{@held.bluebook.name}::#{aggregate.name} (edge #{edge.from} → #{edge.to}, " \
-                   "#{records} record#{'s' unless records == 1})"]
-          verdict.violations.each { |violation| lines << "   REFUSED: #{violation}" }
-          lines << "   dropped (declared data loss): #{verdict.dropped.join(', ')}" unless verdict.dropped.empty?
+          [heading_line(aggregate, edge, records), *verdict_lines(verdict),
+           *verdict.samples.flat_map { |sample| sample_lines(sample) }]
+        end
+
+        def heading_line(aggregate, edge, records)
+          "── #{@held.bluebook.name}::#{aggregate.name} (edge #{edge.from} → #{edge.to}, " \
+            "#{records} record#{"s" unless records == 1})"
+        end
+
+        # What the audit found wrong with, or dropped from, the translated records.
+        def verdict_lines(verdict)
+          lines = verdict.violations.map { |violation| "   REFUSED: #{violation}" }
+          lines << "   dropped (declared data loss): #{verdict.dropped.join(", ")}" unless verdict.dropped.empty?
           unless verdict.unfed.empty?
-            lines << "   unfed (no rule, no default — add default: if required): #{verdict.unfed.join(', ')}"
+            lines << "   unfed (no rule, no default — add default: if required): #{verdict.unfed.join(", ")}"
           end
-          verdict.samples.each { |sample| lines.concat(sample_lines(sample)) }
           lines
         end
 

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        # The text a person reads before attesting to an era whose held text differs from its
+        # digest.
+        module Attestation
+          private
+
+          def attest(held, lineage, ordinal)
+            era = raw_era(held, lineage, ordinal)
+            computed = Digest::SHA256.hexdigest(era[:held_text])
+            return "#{era_name(held, ordinal)}: the held text matches its digest — nothing to re-attest." if
+              era[:held_digest] == computed
+
+            mismatch(held, era, ordinal, computed)
+          end
+
+          def era_name(held, ordinal) = "#{held.bluebook.name} era #{ordinal}"
+
+          def mismatch(held, era, ordinal, computed)
+            [
+              "#{era_name(held, ordinal)}: the held text does NOT match its recorded digest.",
+              "  recorded: #{era[:held_digest] || "(none)"}", "  computed: #{computed}",
+              shape_line(held, era, ordinal),
+              "The held text AS IT NOW STANDS — the original is gone; this is what you would be attesting to:",
+              "─" * 72, era[:held_text], "─" * 72,
+              "Read it, then `hecks reattest #{held.bluebook.name} era=#{ordinal} --confirm` accepts it."
+            ].join("\n")
+          end
+
+          def shape_line(held, era, ordinal)
+            verdict = Translation::Reattest.shape_guard!(
+              domain: held.bluebook.name, ordinal: ordinal, text: era[:held_text], stored_hash: era[:hash],
+              stored_projection: era[:held_projection] && JSON.parse(era[:held_projection])
+            )
+            if verdict == :cosmetic
+              "  shape:    unchanged — the edit is cosmetic (the text still projects to era #{ordinal}'s minted name)"
+            else
+              "  shape:    era #{ordinal} was never named, so no shape comparison is possible — read carefully"
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class JournalStore
+      module Readings
+        # The edge file that would lead the latest held era to the current shape.
+        module Scaffolding
+          private
+
+          def scaffold(held, lineage, path)
+            eras = held.held_eras(lineage)
+            return Readings.no_era(held.bluebook.name, path) if eras.empty?
+
+            scaffold_latest(held, held.named(eras.last))
+          end
+
+          # The edge text for the latest era, or why there is nothing to scaffold.
+          def scaffold_latest(held, latest)
+            shadow = PostgresEra::LineageManager.shadow(latest[:held_text])
+            return "#{held.bluebook.name} matches era #{latest[:ordinal]} — nothing to scaffold." if
+              Runtime::StorageShape.project(shadow) == held.shape
+
+            edge_text(held, latest, Translation::Scaffold.diff(shadow, held.bluebook))
+          end
+
+          def edge_text(held, latest, diffed)
+            label = Runtime::StorageShape.mint_hash(held.bluebook)[0, Runtime::StorageShape::LABEL_LENGTH]
+            edge = Translation::Scaffold::Edge.new(
+              domain: held.bluebook.name, from: latest[:label], to: label, ordinal: latest[:ordinal] + 1,
+              label: label, aggregates: diffed[:aggregates], retired: diffed[:retired]
+            )
+            text = Translation::Scaffold.render(edge)
+            [*scaffold_notes(edge, text, diffed[:unclaimed]), text].join("\n")
+          end
+
+          def scaffold_notes(edge, text, unclaimed)
+            unresolved = text.scan(/^\s*unresolved /).size
+            notes = ["# Save as translations/#{edge.ordinal}-#{edge.label}.bluebook."]
+            notes << "# #{unresolved} unresolved: decide what each became, then boot." if unresolved.positive?
+            unclaimed.each do |name|
+              notes << "# UNCLAIMED: #{name} existed and now doesn't, and its successor is ambiguous — add " \
+                       "`aggregate \"NewName\", was: #{name.inspect}` (with its rules) or `retired #{name.inspect}`."
+            end
+            notes << "# 0 unresolved: this shape change costs one extra boot and no typing." if notes.size == 1
+            notes
+          end
+        end
+      end
+    end
+  end
+end