hecks 2.9.0 → 3.0.1

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

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "console_capture"
+require "hecks/cli/run"
+require "hecks/cli/model_check"
+require "hecks/cli/smoke_test"
+require "hecks/cli/behaviors"
+require "hecks/cli/refresh_projections"
+
+module Hecks
+  module Adapters
+    # What the `DomainRuntime` port's adapter does when a journaled Custodian command asks it to:
+    # the asks of `ModelCheckRun` and `Operation`, plus the `Follow` query.
+    #
+    # An ask is handed the whole record it was made on (its `held_state`), so each method reads the
+    # record's fields, runs the existing `Hecks::CLI::*` entry point captured, and answers the text
+    # 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
+      # The chapters `hecks model_check` sweep when no domain is named need a
+      # checkout; an installed gem has none.
+      CHECKOUT_MARKER = "hecks.gemspec"
+
+      # Longest a `Follow` query may wait for new entries, so one call cannot hold a launcher open.
+      MAX_FOLLOW_WAIT = 60
+
+      # Runs the static analysis over the named domains, or over the whole corpus in a checkout.
+      #
+      # @param held [Hash] the `ModelCheckRun` record: `domains` (comma separated paths), `strict`
+      #   and `profile`
+      # @return [Hash{Symbol => Hash}] `report:` the analysis as printed
+      # @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])
+
+        text = ConsoleCapture.answer do
+          CLI::ModelCheck.call(argv, program: "hecks model_check", root: checkout_root)
+        end
+        { report: { value: text } }
+      end
+
+      # Dispatches one verb, or executes a step list, against a domain.
+      #
+      # @param held [Hash] the `Operation` record: `subject` (the domain), then `script`, or
+      #   `verb` with `arguments` (its `name=value` words)
+      # @return [Hash{Symbol => Hash}] `output:` what the run reported
+      # @raise [ConsoleCapture::Failure] when the verb was refused or an expectation was unmet
+      def execute(**held)
+        argv = [plain(held[:subject])].compact
+        script = plain(held[:script])
+        argv += script ? [script] : [plain(held[:verb]), *words(held[:arguments])].compact
+
+        output(ConsoleCapture.answer { CLI::Run.call(argv, program: "hecks run") })
+      end
+
+      # Forces every read-model projection the domain declares to catch up.
+      #
+      # @param held [Hash] the `Operation` record: `subject` (the domain)
+      # @return [Hash{Symbol => Hash}] `output:` how many projections were refreshed
+      # @raise [Runtime::NotFound] if the domain cannot be found
+      def refresh(**held)
+        count = CLI::RefreshProjections.call(boot(held[:subject]))
+        output("refreshed #{count} projection(s)")
+      end
+
+      # Runs a `.behaviors` file, or every one under a directory.
+      #
+      # @param held [Hash] the `Operation` record: `subject` (the file or directory)
+      # @return [Hash{Symbol => Hash}] `output:` the per-test report
+      # @raise [ConsoleCapture::Failure] when any test failed, errored or did not parse
+      def verify(**held)
+        argv = [plain(held[:subject])].compact
+        output(ConsoleCapture.answer { CLI::Behaviors.call(argv, program: "hecks run_behaviors") })
+      end
+
+      # Boots a wired domain and dispatches one synthesized call per command and report.
+      #
+      # @param held [Hash] the `Operation` record: `subject` (the domain; the enclosing one when
+      #   absent and this is not a checkout)
+      # @return [Hash{Symbol => Hash}] `output:` the per-domain report
+      # @raise [ConsoleCapture::Failure] when any dispatch failed
+      def smoke(**held)
+        domain = plain(held[:subject]) || (checkout_root ? nil : Folder.new.domain_root)
+        argv = [domain].compact
+
+        output(ConsoleCapture.answer { CLI::SmokeTest.call(argv, root: checkout_root || Dir.pwd) })
+      end
+
+      # 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.
+      #
+      # @param domain [Hash, String] a domain directory
+      # @param aggregate [Hash, String, nil] only entries of this aggregate, by bare name
+      # @param since [Hash, Integer, nil] how many entries were already seen; all when absent
+      # @param from_now [Hash, Boolean, nil] skip what exists; answer only a cursor at its end
+      # @param wait [Hash, Integer, nil] seconds to wait for a new entry, at most 60
+      # @param interval [Hash, Float, nil] seconds between checks of the log
+      # @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)
+        registry = boot(domain).registry
+        entries = []
+        cursor = stream(domain: domain, aggregate: aggregate, since: since, from_now: from_now,
+                        timeout: [plain(wait).to_f, MAX_FOLLOW_WAIT].min, interval: interval,
+                        registry: registry) do |entry|
+          entries << entry.merge("payload" => JSON.generate(entry["payload"]))
+          :batch
+        end
+        { cursor: cursor, events: entries, taken_at: Time.at(Ports::Clock.now(registry)).utc.iso8601 }
+      end
+
+      # 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.
+      #
+      # @param domain [Hash, String] a domain directory
+      # @param aggregate [Hash, String, nil] only entries of this aggregate, by bare name
+      # @param since [Hash, Integer, nil] entries already seen; `from_now` skips what exists
+      # @param limit [Hash, Integer, nil] entries to hand over at most, or `timeout` seconds
+      # @param interval [Hash, Float, nil] seconds between checks (0.5 when absent)
+      # @param registry [Runtime::Registry, nil] the domain's booted registry; booted here if absent
+      # @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)
+        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
+      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
+      end
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def output(text) = { output: { value: text } }
+
+      def present?(argument) = !plain(argument).to_s.empty?
+
+      # A list of value objects or bare strings, as plain strings.
+      def words(list) = Array(list).map { |word| plain(word) }
+
+      # The repository root when this is a hecks checkout: `hecks.gemspec` sits beside `lib/`.
+      def checkout_root
+        root = File.expand_path("../../../..", __dir__)
+        root if File.exist?(File.join(root, CHECKOUT_MARKER))
+      end
+
+      def event_repository(domain, registry = nil)
+        registry ||= boot(domain).registry
+        repositories = registry.bluebooks.flat_map do |name, bluebook|
+          bluebook.aggregates.map { |aggregate| registry.repository(name, aggregate) }
+        end
+        repositories.find { |repository| repository.respond_to?(:events) } or
+          raise Runtime::NotFound, "no adapter in #{plain(domain)} persists an event log"
+      end
+
+      # Says whether `event` passes the aggregate filter: a bare name, case-insensitive, or exact.
+      def followed?(event, filter)
+        filter.nil? || event.aggregate.to_s.split("::").last.casecmp?(filter) || event.aggregate == filter
+      end
+    end
+  end
+end

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

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "held_domain"
+require_relative "edge_audit"
+require_relative "compaction"
+require_relative "../git"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      # The changes the journal store makes once `Era.Permit` has let one through.
+      #
+      # The rules that need no database are `given`s of the Era commands, including that a
+      # re-attested text differs from its digest and keeps the era's shape. What stays here is what
+      # only the database can enforce: the connection's write fence, the per-domain advisory lock
+      # and its timeout, the append-only re-attestation, the audit that rolls a merge back, the
+      # monotonic `compacted_through` floor and the row-level-security delete check.
+      module Changes
+        # Makes the change the record asks for.
+        #
+        # A change is made only for a record `Era.Permit` admitted, whichever way `apply` is asked.
+        #
+        # @param held [Hash] the `Era` record
+        # @return [Hash{Symbol => Hash}] `report:` what was done, as the script said it
+        # @raise [Runtime::WiringError] if the record was not admitted, or the database or an
+        #   era's own guard refuses the change
+        # @raise [Runtime::NotFound] if the domain cannot be loaded
+        def apply(**held)
+          unless plain(held[:status]) == "admitted"
+            raise Runtime::WiringError,
+                  "the change was not admitted (status #{plain(held[:status]).inspect}): " \
+                  "only an admitted change is made"
+          end
+
+          { report: { value: send(:"apply_#{plain(held[:operation])}", held) } }
+        end
+
+        private
+
+        def apply_hold_first(held)
+          domain = HeldDomain.open(plain(held[:domain]), mode: :bare)
+          domain.writing do |lineage|
+            raise Runtime::WiringError, "#{domain.bluebook.name} already holds an era" unless lineage.eras.empty?
+
+            lineage.hold_first!(domain.source_text, projection: domain.shape)
+          end
+          "#{domain.bluebook.name} holds era 1 now."
+        end
+
+        def apply_merge_tail(held)
+          domain = HeldDomain.open(plain(held[:domain]))
+          named = winners(held)
+          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 " \
+           "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")
+        end
+
+        def diverged_writes(domain, lineage)
+          eras = domain.held_eras(lineage)
+          eras.size > 1 ? (1...eras.last[:ordinal]).sum { |era| lineage.diverged_count(era) } : 0
+        end
+
+        def apply_reattest(held)
+          domain = HeldDomain.open(plain(held[:domain]), mode: :bare)
+          ordinal = plain(held[:era])
+          domain.writing { |lineage| reattest(domain, lineage, ordinal) }
+        end
+
+        def reattest(domain, lineage, ordinal)
+          lineage.raw_era(ordinal) or raise Runtime::NotFound, "#{domain.bluebook.name} holds no era #{ordinal}"
+          fresh = lineage.reattest!(ordinal)
+          "ATTESTED: era #{ordinal} re-frozen as #{fresh[0, 12]}… — the old and new digests are recorded."
+        end
+
+        def apply_backfill_projections(held)
+          domain = HeldDomain.open(plain(held[:domain]), mode: :bare)
+          domain.writing { |lineage| backfill(domain, lineage) }
+        end
+
+        def backfill(domain, lineage)
+          missing = -> { missing_projections(lineage) }
+          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
+          done = before - missing.call
+          "#{domain.bluebook.name}: backfilled #{done} era#{'s' unless done == 1} — every row now carries a projection."
+        end
+
+        def missing_projections(lineage)
+          lineage.db.exec_params(
+            "SELECT count(*)::int AS n FROM hecks_eras WHERE domain = $1 AND held_projection IS NULL",
+            [lineage.domain]
+          )[0]["n"].to_i
+        end
+
+        def apply_compact(held) = apply_compaction(held, :entries)
+
+        def apply_compact_heki(held) = apply_compaction(held, :heki)
+
+        def apply_compaction(held, kind)
+          Compaction.new(plain(held[:domain]), aggregates: names(held[:aggregates]), kind: kind).apply!.join("\n")
+        end
+
+        # Writes `translations/<edge>.approval`; the host reads it at its next boot.
+        def apply_approve_translation(held)
+          domain = HeldDomain.open(plain(held[:domain]))
+          finding = domain.reading { |lineage| audited_edge(domain, lineage) }
+          document = 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)
+          eras = domain.held_eras(lineage)
+          finding = eras.empty? ? nil : EdgeAudit.call(domain, lineage, eras)
+          raise Runtime::WiringError, "#{domain.bluebook.name} has no edge to approve" unless finding
+          raise Runtime::WiringError, "#{finding.report}\nAUDIT REFUSED." unless finding.ok
+
+          finding
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "hecks"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      # The journals of one booted domain that can be compacted, and what compacting them does.
+      #
+      # `:entries` are Postgres and Sqlite journals, compacted through the aggregate's own
+      # checkpoint (`compact_entries!`); `:heki` journals are compacted to empty (`compact!`),
+      # the snapshot keeping the current state. The database-level guard, that the
+      # `compacted_through` floor only moves forward, stays in the adapter that owns the journal.
+      class Compaction
+        Candidate = Struct.new(:domain_name, :aggregate, :adapter, keyword_init: true)
+
+        KINDS = { entries: %i[compact_entries! checkpoint], heki: %i[compact!] }.freeze
+
+        # @param path [String] the domain directory
+        # @param aggregates [Array<String>] aggregate names or storage names; every one when empty
+        # @param kind [Symbol] `:entries` or `:heki`
+        # @raise [Runtime::NotFound] if the directory does not exist
+        def initialize(path, aggregates:, kind:)
+          raise Runtime::NotFound, "no such domain #{path.inspect}" unless Dir.exist?(path.to_s)
+
+          @registry = Hecks.boot(File.expand_path(path), install_doors: false).registry
+          @wanted = aggregates
+          @kind = kind
+        end
+
+        # @return [Array<Candidate>] the aggregates whose journals this kind can compact
+        def candidates
+          @candidates ||= @registry.bluebooks.flat_map do |domain_name, bluebook|
+            bluebook.aggregates.filter_map { |aggregate| candidate(domain_name, aggregate) }
+          end
+        end
+
+        # The candidates a `projected_by` binding reads: their projections replay the full journal.
+        #
+        # @return [Array<Candidate>] the bound candidates
+        def bound
+          candidates.select do |candidate|
+            Ports::Projection.binds_for(@registry, candidate.domain_name, candidate.aggregate).any?
+          end
+        end
+
+        # What compacting would do, without doing it.
+        #
+        # @return [Array<String>] one line per candidate
+        def preview
+          candidates.map { |candidate| bound.include?(candidate) ? refusal_line(candidate) : dry_line(candidate) }
+        end
+
+        # Compacts every candidate.
+        #
+        # @return [Array<String>] one line per candidate
+        # @raise [Runtime::WiringError] if a projection reads a journal that would be emptied, or
+        #   the journal's own floor refuses the compaction
+        def apply!
+          raise Runtime::WiringError, preview.grep(/^REFUSED/).join("\n") if bound.any?
+
+          candidates.map { |candidate| kind_apply(candidate) }
+        end
+
+        private
+
+        def candidate(domain_name, aggregate)
+          return unless @wanted.empty? || @wanted.include?(aggregate.hecks_name) || @wanted.include?(aggregate.storage_name)
+
+          repository = @registry.repository(domain_name, aggregate)
+          return unless repository.is_a?(Ports::Persistence::AppendOnly)
+
+          adapter = repository.adapter
+          return unless KINDS.fetch(@kind).all? { |operation| adapter.respond_to?(operation) }
+
+          Candidate.new(domain_name: domain_name, aggregate: aggregate, adapter: adapter)
+        end
+
+        def kind_apply(candidate)
+          @kind == :heki ? compact_heki(candidate) : compact_entries(candidate)
+        end
+
+        def dry_line(candidate)
+          @kind == :heki ? heki_dry(candidate) : entries_dry(candidate)
+        end
+
+        def refusal_line(candidate)
+          "REFUSED #{candidate.aggregate.storage_name}: a projected_by binding reads its full journal — " \
+            "compacting would break its catch-up. Not compacted."
+        end
+
+        def entries_dry(candidate)
+          name = candidate.aggregate.storage_name
+          adapter = candidate.adapter
+          through = adapter.checkpoint
+          if through <= adapter.compacted_through
+            return "SKIP #{name}: nothing new to compact (already compacted through #{through})"
+          end
+
+          "DRY RUN #{name}: would delete journal entries through sequence #{through} (compacted_through is " \
+            "currently #{adapter.compacted_through}); current state (#{adapter.count} records) is unaffected."
+        end
+
+        def compact_entries(candidate)
+          name = candidate.aggregate.storage_name
+          adapter = candidate.adapter
+          through = adapter.checkpoint
+          if through <= adapter.compacted_through
+            return "SKIP #{name}: nothing new to compact (already compacted through #{through})"
+          end
+
+          removed = adapter.compact_entries!(through: through)
+          "COMPACTED #{name}: deleted #{removed} journal entries through sequence #{through}; " \
+            "#{adapter.count} records preserved"
+        end
+
+        def heki_dry(candidate)
+          name = candidate.aggregate.storage_name
+          adapter = candidate.adapter
+          return "SKIP #{name}: journal already empty" if adapter.entries.empty?
+
+          "DRY RUN #{name}: would discard #{adapter.entries.length} journal entries (#{journal_bytes(adapter)} " \
+            "bytes) at #{adapter.path}.journal; current state (#{adapter.count} records) is unaffected."
+        end
+
+        def compact_heki(candidate)
+          name = candidate.aggregate.storage_name
+          adapter = candidate.adapter
+          entries = adapter.entries.length
+          return "SKIP #{name}: journal already empty" if entries.zero?
+
+          bytes = journal_bytes(adapter)
+          adapter.compact!
+          "COMPACTED #{name}: discarded #{entries} journal entries (#{bytes} bytes freed); " \
+            "#{adapter.count} records preserved at #{adapter.path}"
+        end
+
+        def journal_bytes(adapter)
+          path = "#{adapter.path}.journal"
+          File.exist?(path) ? File.size(path) : 0
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "held_domain"
+
+module Hecks
+  module Adapters
+    class JournalStore
+      # The translation audit of the edge that leads a domain's latest held era to its current
+      # shape, without holding or naming anything: an era that has no name yet is named in memory.
+      #
+      # It answers what the audit's three layers found, as the report `hecks audit_translation`
+      # prints, and the edge itself, so approving it audits the very edge that was read.
+      class EdgeAudit
+        # What one audit found.
+        #
+        # @!attribute [r] edge
+        #   @return [Bluebook::Translation] the audited edge
+        # @!attribute [r] leaving
+        #   @return [Integer] how many edges leave the latest held era
+        # @!attribute [r] ok
+        #   @return [Boolean] whether no layer refused
+        # @!attribute [r] report
+        #   @return [String] the report, one block per aggregate
+        Finding = Struct.new(:edge, :leaving, :ok, :report, keyword_init: true)
+
+        # Audits the edge that leaves the latest held era.
+        #
+        # @param held [HeldDomain] the loaded domain, translation edges included
+        # @param lineage [Lineage] the domain's lineage
+        # @param eras [Array<Hash>] the eras the lineage holds, at least one
+        # @return [Finding, nil] the finding; nil when the domain stands at era 1, with no edge
+        # @raise [Runtime::NotFound] if no edge leads the latest era to the current shape, or a
+        #   preview query is refused by Postgres
+        def self.call(held, lineage, eras)
+          new(held, lineage, eras).call
+        end
+
+        # @param held [HeldDomain] the loaded domain
+        # @param lineage [Lineage] the domain's lineage
+        # @param eras [Array<Hash>] the held eras
+        def initialize(held, lineage, eras)
+          @held = held
+          @lineage = lineage
+          @eras = eras
+          @manager = PostgresEra::LineageManager
+        end
+
+        # @return [Finding, nil] see `EdgeAudit.call`
+        def call
+          latest = @held.named(@eras.last)
+          if @held.shape == Runtime::StorageShape.project(@manager.shadow(latest[:held_text]))
+            return nil if latest[:ordinal] == 1
+
+            settled(latest)
+          else
+            pending(latest)
+          end
+        end
+
+        private
+
+        # The shape already minted: the edge that arrives at the latest era.
+        def settled(latest)
+          chain = @manager.edge_chain(@held.registry, @held.bluebook, @eras[0..-2], latest[:label])
+          finding(chain, latest[:ordinal], 1)
+        end
+
+        # 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
+            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
+
+        def finding(chain, era, leaving, edge = chain.last[:translation])
+          lines = []
+          ok = true
+          @held.bluebook.aggregates.each do |aggregate|
+            verdict, records = verdict_for(aggregate, edge, era, chain)
+            lines.concat(describe(aggregate, edge, verdict, records))
+            ok &&= verdict.ok?
+          end
+          Finding.new(edge: edge, leaving: leaving, ok: ok, report: lines.join("\n"))
+        end
+
+        def verdict_for(aggregate, edge, era, chain)
+          after = translated(aggregate, era, chain)
+          before = if chain.size > 1
+                     translated(aggregate, era, chain[0..-2])
+                   else
+                     @lineage.ancestor_latest(aggregate, era, chain)
+                   end
+          verdict = Translation::Audit.check(aggregate: aggregate, declared: edge.for_aggregate(aggregate.name),
+                                             before: before, after: after)
+          [verdict, after.size]
+        end
+
+        def translated(aggregate, era, chain)
+          @lineage.translated_latest(aggregate, era, chain)
+        rescue PG::Error => e
+          raise Runtime::NotFound, "REFUSED: #{e.message.strip}"
+        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?
+          unless verdict.unfed.empty?
+            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
+
+        def sample_lines(sample)
+          lines = ["   ##{sample[:id]}"]
+          lines << "     before: #{JSON.generate(sample[:before])}" if sample[:before]
+          lines << "     after:  #{JSON.generate(sample[:after])}" if sample[:after]
+          lines
+        end
+      end
+    end
+  end
+end