hecks 2.9.0 → 3.0.0

data/lib/hecks/persistence_legacy_fixture.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "json"
+require "hecks"
+require "fileutils"
+
+module Hecks
+  # The seed records of `spec/fixtures/persistence_legacy/`, over `examples/banking`, and the
+  # regeneration of those fixtures through the real adapters.
+  #
+  # Banking's IR only: no hecksagon, no boot; adapters are built straight from `aggregate:`.
+  module PersistenceLegacyFixture
+    # The gem's root directory.
+    ROOT = File.expand_path("../..", __dir__)
+    # Where the fixtures stand in a checkout.
+    DIR  = File.join(ROOT, "spec/fixtures/persistence_legacy").freeze
+
+    # Each seed: aggregate name, id and field values.
+    SEEDS = [
+      [
+        "Account", "ACC-1",
+        {
+          number:          { value: "ACC-1" },
+          customer:        "CUST-1",
+          balance:         { cents: 1250, currency: "USD" },
+          kind:            { name: "current" },
+          daily_limit:     { cents: 500 },
+          ledger:          [
+            { sequence: { value: 1 }, amount: { cents: 1000, currency: "USD" }, narrative: { text: "opening" },
+              direction: { value: "credit" }, state: "posted" },
+            { sequence: { value: 2 }, amount: { cents: 250, currency: "USD" }, narrative: { text: "top up" },
+              direction: { value: "credit" }, state: "reversed" }
+          ],
+          status:          "open",
+          customer_status: "active"
+        }
+      ],
+      [
+        "CardPayment", "AUTH-1",
+        {
+          authorisation:  { value: "AUTH-1" },
+          account:        "ACC-1",
+          amount:         { cents: 300 },
+          merchant:       { value: "Cafe" },
+          tags:           [{ value: "food" }, { value: "travel" }],
+          status:         "authorized",
+          account_status: "open"
+        }
+      ]
+    ].freeze
+
+    module_function
+
+    # @return [Hecks::Bluebook::Structure::Domain] banking's bluebook, loaded once
+    def bluebook
+      @bluebook ||= begin
+        registry = Hecks::Runtime::Registry.new
+        Hecks.with_registry(registry) do
+          Kernel.load(File.join(ROOT, "lib/hecks/ports/persistence.port"))
+          Kernel.load(File.join(ROOT, "lib/hecks/ports/extraction.port"))
+          Kernel.load(File.join(ROOT, "lib/hecks/adapters/driven/prism.adapter"))
+          folder = Hecks::Adapters::Folder.new
+          folder.load_bluebooks(folder.bluebook_directory(File.join(ROOT, "examples/banking/bluebook")))
+        end
+        registry.bluebook("Banking")
+      end
+    end
+
+    # @param name [String] an aggregate of banking
+    # @return [Object] its definition
+    def aggregate(name) = bluebook.aggregate(name)
+
+    # @return [Array<Hecks::Runtime::Instance>] one instance for each seed
+    def instances
+      SEEDS.map do |name, id, fields|
+        aggregate = aggregate(name)
+        instance = Hecks::Runtime::Instance.new(aggregate: aggregate, id: id)
+        fields.each { |field, value| instance[field] = Hecks::Runtime::Value.for(aggregate, field, value) }
+        instance
+      end
+    end
+
+    # In-memory SQLite answering `Connection`'s four methods, as `d1_spec.rb` does.
+    #
+    # @return [Object] the connection
+    def fake_d1_connection
+      require "sqlite3"
+      db = SQLite3::Database.new(":memory:")
+      db.results_as_hash = true
+      Class.new do
+        def initialize(db) = @db = db
+        def execute(sql, binds = []) = @db.execute(sql, binds)
+        def get_first_row(sql, binds = []) = execute(sql, binds).first
+        def get_first_value(sql, binds = []) = get_first_row(sql, binds)&.values&.first
+      end.new(db)
+    end
+
+    # Makes `D1::Connection.new` answer `connection` for the length of the block.
+    #
+    # @param connection [Object] the connection to answer
+    # @yield the work that builds a D1 adapter
+    # @return [Object] the block's value
+    def with_d1_connection(connection)
+      klass = Hecks::Adapters::D1::Connection
+      klass.define_singleton_method(:new) { |**| connection }
+      yield
+    ensure
+      klass.singleton_class.send(:remove_method, :new) if klass.singleton_class.method_defined?(:new, false)
+    end
+  end
+end
+
+require_relative "persistence_legacy_fixture/regenerate"

data/lib/hecks/ports/persistence/plugins/era/era_check.rb

@@ -3,6 +3,7 @@ require_relative "../../../../ports/persistence/binding_policy"
 require_relative "lineage"
 require_relative "../../../../naming"
 require_relative "../../../../framework"
+require_relative "../../../../chapters"
 require_relative "../../../../runtime/registry"
 require_relative "expected_era"
 
@@ -115,21 +116,23 @@ module Hecks
 
       # Picks the files to read for a bluebook no file in the domain directory declares.
       #
-      # Tries, in order: the domain's own single remaining file, a framework member, then a
-      # vendored embryonaut bluebook.
+      # Tries, in order: a chapter the gem carries (the QA ledger's QualityControl), the domain's
+      # own single remaining file, a framework member, then a vendored embryonaut bluebook.
       #
       # @param bluebook [Bluebook::Chapter] the bluebook whose source is wanted
       # @param directory [String] path of the domain's own bluebook directory
       # @param domain_files [Array<String>] paths of every `.bluebook` file in `directory`
       # @param registry [Runtime::Registry, nil] the registry asked for a vendored name; nil
       #   skips the vendored lookup
-      # @return [Array<String>] file paths to read, in load order; `[]` when the bluebook
-      #   comes from none of the three sources
+      # @return [Array<String>] file paths to read, in load order; `[]` when none applies
       def fallback_source_files(bluebook, directory, domain_files, registry)
         vendored_name = registry && vendored_bluebook_name_for(registry, bluebook.name)
         framework_path = Framework.members[bluebook.name]
+        attached = Chapters.index.fetch(bluebook.name, [])
 
-        if domain_files.size == 1 && !framework_path && !vendored_name
+        if attached.any? && !framework_path && !vendored_name
+          attached
+        elsif domain_files.size == 1 && !framework_path && !vendored_name
           domain_files
         elsif framework_path
           [framework_path]

data/lib/hecks/ports/persistence/plugins/era/era_guard.rb

@@ -139,7 +139,10 @@ module Hecks
         run = lambda do
           Hecks.with_registry(scratch) do
             loading.load_library
-            Kernel.eval(source, TOPLEVEL_BINDING, path, 1)
+            # Held text of a chapter spread over files is several blocks in one string, each
+            # opening the same chapter: judge once after all of them, as a directory load does.
+            Hecks::Bluebook::MetaValidator.defer { Kernel.eval(source, TOPLEVEL_BINDING, path, 1) }
+            Hecks::Bluebook::MetaValidator.judge_deferred!(scratch)
           end
         end
         shadow ? Hecks::Bluebook::MetaValidator.while_shadow_parsing(&run) : run.call

data/lib/hecks/ports/persistence/plugins/era/expected_era.rb

@@ -59,13 +59,26 @@ module Hecks
         # @raise [Unreachable] if the request fails or the status is not `200`
         # @raise [BadResponse] if the body is not JSON or its `era` is not a non-empty string
         def fetch_era(url, timeout: 10)
+          fetch_version(url, timeout: timeout).fetch("era")
+        end
+
+        # Asks a host for its `/version` document.
+        #
+        # @param url [String] the host's base URL, or its `/version` URL
+        # @param timeout [Numeric] seconds allowed for connecting and for reading
+        # @return [Hash{String => String}] `"era"` (never empty) and `"version"` (empty when the
+        #   host reports none)
+        # @raise [Unreachable] if the request fails or the status is not `200`
+        # @raise [BadResponse] if the body is not JSON or its `era` is not a non-empty string
+        def fetch_version(url, timeout: 10)
           response = get(version_url(url), timeout)
           raise Unreachable, "#{version_url(url)} answered #{response.code}" unless response.code == "200"
 
-          era = JSON.parse(response.body)["era"]
+          document = JSON.parse(response.body)
+          era = document["era"]
           raise BadResponse, "#{version_url(url)} carries no era" unless era.is_a?(String) && !era.empty?
 
-          era
+          { "era" => era, "version" => document["version"].to_s }
         rescue JSON::ParserError, TypeError
           raise BadResponse, "#{version_url(url)} did not answer a JSON version document"
         end

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage/era_store.rb

@@ -22,7 +22,7 @@ module Hecks
             end
           end
 
-          # Skips the integrity check `eras` runs, so bin/reattest_era can show the raw row first.
+          # Skips the integrity check `eras` runs, so hecks reattest can show the raw row first.
           def raw_era(ordinal)
             rows = @db.exec_params(
               "SELECT held_text, held_digest, hash, held_projection::text FROM hecks_eras WHERE domain = $1 AND ordinal = $2",

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage/tail_merge.rb

@@ -53,7 +53,7 @@ module Hecks
               raise Runtime::WiringError,
                     "cannot merge the tail of #{@domain}: touched by both worlds since the cut — " \
                     "#{unresolved.map { |storage, id| "#{storage}##{id}" }.sort.join(', ')}. " \
-                    "Name each winner (--winner <id>=old or --winner <id>=new), then run bin/merge_tail again. " \
+                    "Name each winner (--winner <id>=old or --winner <id>=new), then run hecks merge_tail again. " \
                     "A winner takes the WHOLE record — the aggregate is the consistency boundary, so the " \
                     "loser's edits are discarded even where they touched different attributes"
             end

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/merge_coordinator.rb

@@ -6,7 +6,7 @@ module Hecks
   module Adapters
     class PostgresEra
       module LineageManager
-        # Tail-merge (bin/merge_tail): interleaves the stale world's post-cut writes into the
+        # Tail-merge (hecks merge_tail): interleaves the stale world's post-cut writes into the
         # head by global ordinal, audited, in one transaction.
         module MergeCoordinator
           # Merges writes old checkouts made after the last mint into the current era's head.

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/minter.rb

@@ -2,6 +2,7 @@ require_relative "../../../../../../runtime/registry"
 require_relative "../../storage_shape"
 require_relative "../../translation/audit"
 require_relative "../../translation/scaffold"
+require_relative "../../translation/approval_file"
 
 module Hecks
   module Adapters
@@ -20,7 +21,7 @@ module Hecks
             ordinal = latest[:ordinal] + 1
 
             edge = resolve_edge!(registry, bluebook, lineage, latest, label, ordinal, directory)
-            ensure_compute_rekey_approved!(bluebook, lineage, edge, ordinal)
+            ensure_compute_rekey_approved!(bluebook, lineage, edge, ordinal, directory: directory)
             check_coverage!(registry, bluebook, shadow(latest[:held_text]), edge)
 
             chain = edge_chain(registry, bluebook, lineage.eras, label)
@@ -49,32 +50,48 @@ module Hecks
             unless edge.to == label
               raise Runtime::WiringError,
                     "cannot boot #{bluebook.name}: the translation edge from #{latest[:label]} targets " \
-                    "#{edge.to}, but the current shape is #{label} — the edge is stale; re-run bin/scaffold_translation"
+                    "#{edge.to}, but the current shape is #{label} — the edge is stale; re-run hecks scaffold_translation"
             end
             edge
           end
 
-          # Refuses a mint whose edge carries a compute or rekey rule without a recorded,
-          # edge-matching, journal-current approval.
+          # Refuses a mint whose edge carries a compute or rekey rule without an approval.
           #
-          # A compute or rekey's only verification is a human-approved audit sample.
-          def ensure_compute_rekey_approved!(bluebook, lineage, edge, ordinal)
-            return unless edge.aggregates.any? { |declared| !declared.computes.empty? || !declared.rekeys.empty? }
+          # A compute or rekey's only verification is a human-approved audit sample. Two approvals
+          # satisfy it: one recorded in the journal that matches the edge and the journal's current
+          # tip, or a committed `translations/<edge>.approval` that matches the edge's digest and
+          # records a passed rehearsal on a compatible host release. A committed approval that
+          # applies is written into the journal, so the journal stays the single history.
+          def ensure_compute_rekey_approved!(bluebook, lineage, edge, ordinal, directory: nil)
+            return unless Translation::ApprovalFile.needs_rehearsal?(edge)
 
             approval = lineage.approval_for(from: edge.from, to: edge.to)
-            unless approval && approval[:edge_digest] == Translation::Audit.edge_digest(edge)
+            digest = Translation::Audit.edge_digest(edge)
+            tip = lineage.last_ordinal
+            return if approval && approval[:edge_digest] == digest && approval[:reviewed_ordinal] == tip
+
+            if Translation::ApprovalFile.applicable(directory, edge)
+              lineage.record_approval!(from: edge.from, to: edge.to, edge_digest: digest)
+              return
+            end
+
+            unless approval && approval[:edge_digest] == digest
+              if (mismatch = Translation::ApprovalFile.host_mismatch(directory, edge))
+                raise Runtime::WiringError,
+                      "cannot mint era #{ordinal} of #{bluebook.name}: the committed approval does not " \
+                      "apply — #{mismatch}"
+              end
+
               raise Runtime::WiringError,
                     "cannot mint era #{ordinal} of #{bluebook.name}: this edge carries a compute or rekey " \
                     "rule, and the audit's human-approved sample is its only verification — run " \
-                    "bin/translation_audit with --approve, then boot again"
+                    "hecks audit_translation with --approve, then boot again"
             end
-            tip = lineage.last_ordinal
-            return unless approval[:reviewed_ordinal] != tip
 
             raise Runtime::WiringError,
                   "cannot mint era #{ordinal} of #{bluebook.name}: the journal advanced past the approved " \
                   "review (ordinal #{approval[:reviewed_ordinal]} reviewed, #{tip} now) — the samples a " \
-                  "human approved no longer cover the data; re-run bin/translation_audit with --approve"
+                  "human approved no longer cover the data; re-run hecks audit_translation with --approve"
           end
 
           # Refuses toward the authoring loop, or, under HECKS_SCAFFOLD=1, scaffolds the
@@ -84,13 +101,13 @@ module Hecks
               path = scaffold!(registry, bluebook, lineage, latest, directory)
               raise Runtime::WiringError,
                     "cannot boot #{bluebook.name}: the shape changed (era #{ordinal}) — wrote #{path}; " \
-                    "review it (resolve every unresolved), check it with bin/translation_audit, then boot again"
+                    "review it (resolve every unresolved), check it with hecks audit_translation, then boot again"
             end
 
             raise Runtime::WiringError,
                   "cannot boot #{bluebook.name}: the shape changed (era #{ordinal}) and no translation edge " \
-                  "covers it — run bin/scaffold_translation to write the edge, " \
-                  "check it with bin/translation_audit, then boot again"
+                  "covers it — run hecks scaffold_translation to write the edge, " \
+                  "check it with hecks audit_translation, then boot again"
           end
 
           # Diffs the held era against the current shape and writes the edge file —

data/lib/hecks/ports/persistence/plugins/era/postgres_era.rb

@@ -3,6 +3,7 @@ require "json"
 require_relative "../../../../adapters/driven/sql_query_builder"
 require_relative "../../../../adapters/driven/postgres/outbox"
 require_relative "../../../../adapters/driven/postgres/reconnect"
+require_relative "../../../../adapters/driven/postgres/shared_connection"
 require_relative "postgres_era/lineage"
 require_relative "postgres_era/lineage_manager"
 require_relative "postgres_era/events"
@@ -118,8 +119,10 @@ module Hecks
               "cannot bind PostgresEra at #{declared} for #{name}: #{e.message.strip}"
       end
 
-      # Connects and provisions the journal, this aggregate's head and field caches, and the
-      # event, saga and outbox tables. Every step is idempotent.
+      # Joins the process's shared connection for the declared database and schema, so every
+      # aggregate of a domain runs on one connection, then provisions the journal, this
+      # aggregate's head and field caches, and the event, saga and outbox tables. Every step is
+      # idempotent.
       #
       # @param settings [Hash{Symbol, String => Object}] world settings plus what
       #   `RepositoryFactory.build` merges in: `domain`, `era` and `superseded_by`
@@ -127,7 +130,7 @@ module Hecks
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
         @settings  = settings
-        @db = self.class.connect_for(aggregate.name, settings)
+        @db = PostgresSharedConnection.for(aggregate.name, settings, connector: self.class)
         # Journal name: the owning bluebook's declared name, matching the key rust/host derives its
         # advisory lock from (ADR 0036). A bare aggregate with no owner falls back to its own name.
         @domain = self.class.setting(

data/lib/hecks/ports/persistence/plugins/era/translation/approval_file.rb

@@ -0,0 +1,227 @@
+require "json"
+require "date"
+require "fileutils"
+require_relative "audit/approval_digest"
+require_relative "../../../../../version"
+
+module Hecks
+  module Translation
+    # The committed form of an edge's approval: `translations/<edge>.approval`, a JSON file beside
+    # the edge that a reviewer sees in the same diff.
+    #
+    # It binds to the edge's content digest and not to the journal's tip, so a production journal
+    # that keeps writing between the commit and the deploy does not void it. An edge with a compute
+    # or rekey rule also carries the rehearsal a person ran against real data, since the audit's
+    # samples are that edge's only other verification.
+    module ApprovalFile
+      EXTENSION = ".approval".freeze
+
+      # The keys of a rehearsal block; every one is required when the block is required.
+      #
+      # `host_version` is the Hecks release the rehearsal ran on, and the gate checks it: a
+      # rehearsal counts only on a host whose release shares its `major.minor` (see
+      # `host_compatible?`).
+      REHEARSAL_KEYS = %w[snapshot host_version result at].freeze
+
+      # How a `host_version` reads: `major.minor`, an optional patch, an optional pre-release or
+      # build suffix. Only the first two numbers take part in the comparison.
+      HOST_LINE = /\A(\d+)\.(\d+)(?:\.\d+)?(?:[-+][0-9A-Za-z.+-]+)?\z/
+
+      # The release the running host reports: the Hecks release this code was built for. The Rust
+      # host embeds the same string from `rust/host/HECKS_RELEASE`, and a spec fails when the two
+      # drift.
+      HOST_RELEASE = Hecks::VERSION
+
+      # An ISO 8601 time: `2026-09-28T12:30:00Z`, with optional fraction and `+HH:MM` offset. The
+      # host's approval.rs accepts the same shape.
+      TIMESTAMP = /\A(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})\z/
+
+      extend Audit::ApprovalDigest
+
+      module_function
+
+      # Names an edge by the labels it joins; labels are hex, so the dash cannot be part of one.
+      #
+      # @param edge [Bluebook::Translation] the parsed translation edge
+      # @return [String] `<from>-<to>`
+      def edge_name(edge) = "#{edge.from}-#{edge.to}"
+
+      # Where an edge's approval lives.
+      #
+      # @param directory [String] the domain's bluebook directory
+      # @param edge [Bluebook::Translation] the parsed translation edge
+      # @return [String] `<directory>/translations/<edge>.approval`
+      def path_for(directory, edge) = File.join(directory, "translations", "#{edge_name(edge)}#{EXTENSION}")
+
+      # Whether the edge carries a rule whose only verification is a human's review of samples.
+      #
+      # @param edge [Bluebook::Translation] the parsed translation edge
+      # @return [Boolean] true when any aggregate declares a compute or a rekey
+      def needs_rehearsal?(edge)
+        edge.aggregates.any? { |declared| !declared.computes.empty? || !declared.rekeys.empty? }
+      end
+
+      # Whether a rehearsal block records a run that passed, with every field named.
+      #
+      # @param rehearsal [Hash, nil] the block, string-keyed as it reads from JSON
+      # @return [Boolean] true when all of `REHEARSAL_KEYS` are non-empty Strings and `result` is
+      #   `pass`
+      def rehearsed?(rehearsal)
+        return false unless rehearsal.is_a?(Hash)
+
+        REHEARSAL_KEYS.all? { |key| named?(rehearsal[key]) } && rehearsal["result"] == "pass"
+      end
+
+      # The `major.minor` a version names.
+      #
+      # @param version [Object] a `host_version` as it reads from JSON
+      # @return [Array<Integer>, nil] `[major, minor]`, or nil when it is not a version
+      def release_line(version)
+        match = HOST_LINE.match(version) if version.is_a?(String)
+        match && [match[1].to_i, match[2].to_i]
+      end
+
+      # Whether a rehearsal ran on a host compatible with the running one.
+      #
+      # The rule is the smallest sound one: equal `major.minor`. A patch release does not change
+      # what a mint does, so a rehearsal survives it; a minor or major release may, so a rehearsal
+      # from an older host (or a newer one, which proves nothing about this one) does not.
+      #
+      # @param rehearsal [Hash] a rehearsal block, string-keyed
+      # @param host_version [String] the running host's release
+      # @return [Boolean] true when both versions parse and share `major.minor`
+      def host_compatible?(rehearsal, host_version = HOST_RELEASE)
+        line = release_line(rehearsal["host_version"])
+        !line.nil? && line == release_line(host_version)
+      end
+
+      # The refusal for a rehearsal that ran on another host line; rust/host words it the same.
+      #
+      # @param rehearsal [Hash] a rehearsal block, string-keyed
+      # @param host_version [String] the running host's release
+      # @return [String] names both versions
+      def host_refusal(rehearsal, host_version = HOST_RELEASE)
+        line = release_line(host_version)&.join(".")
+        "the rehearsal ran on Hecks #{rehearsal['host_version']}, but this host is Hecks #{host_version}; " \
+          "a rehearsal counts only on a host of the same major.minor (#{line}.x) — " \
+          "re-run the rehearsal on this host and approve again"
+      end
+
+      # Whether a value is a String with something in it; a number or nil names nothing.
+      #
+      # @param value [Object] a field as it reads from JSON
+      # @return [Boolean] true for a String that is not blank
+      def named?(value) = value.is_a?(String) && !value.strip.empty?
+
+      # Whether a value is an ISO 8601 time that exists on the calendar.
+      #
+      # @param value [Object] a field as it reads from JSON
+      # @return [Boolean] true for a String of the `TIMESTAMP` shape with a real date and clock time
+      def timestamp?(value)
+        return false unless value.is_a?(String) && (match = TIMESTAMP.match(value))
+
+        year, month, day, hour, minute, second = match.captures.map(&:to_i)
+        Date.valid_date?(year, month, day) && hour < 24 && minute < 60 && second < 60
+      end
+
+      # Whether an approval names who approved it and when, the two things a reviewer signs.
+      #
+      # @param approval [Hash] the file, string-keyed as it reads from JSON
+      # @return [Boolean] true when `approved_by` is a non-empty String and `approved_at` a time
+      def attributed?(approval)
+        named?(approval["approved_by"]) && timestamp?(approval["approved_at"])
+      end
+
+      # Builds the JSON document of one approval.
+      #
+      # @param edge [Bluebook::Translation] the parsed translation edge
+      # @param approved_by [String] who approved it, from their git identity
+      # @param approved_at [String] when, as an ISO 8601 UTC time
+      # @param rehearsal [Hash{String => String}, nil] the block; required for a compute or rekey
+      # @return [Hash{String => Object}] `edge`, `edge_digest`, `approved_by`, `approved_at`, and
+      #   `rehearsal` when one was given
+      # @raise [ArgumentError] if `approved_by` is blank or `approved_at` is not a time, or if the
+      #   edge needs a rehearsal and none that passed was given
+      def build(edge:, approved_by:, approved_at:, rehearsal: nil)
+        unless attributed?("approved_by" => approved_by, "approved_at" => approved_at)
+          raise ArgumentError, "an approval names who approved it (approved_by, your git identity) " \
+                               "and when (approved_at, an ISO 8601 time)"
+        end
+
+        if needs_rehearsal?(edge) && !rehearsed?(rehearsal)
+          raise ArgumentError, "an edge with a compute or rekey rule is approved on a rehearsal that passed: " \
+                               "name the snapshot, the host version, the result (pass) and when it ran"
+        end
+
+        document = { "edge" => edge_name(edge), "edge_digest" => edge_digest(edge),
+                     "approved_by" => approved_by, "approved_at" => approved_at }
+        document["rehearsal"] = rehearsal.slice(*REHEARSAL_KEYS) if rehearsal
+        document
+      end
+
+      # Writes an edge's approval file, replacing an earlier approval of the same edge.
+      #
+      # @param directory [String] the domain's bluebook directory
+      # @param edge [Bluebook::Translation] the parsed translation edge
+      # @param document [Hash{String => Object}] what `build` answered
+      # @return [String] the path written
+      def write!(directory, edge, document)
+        path = path_for(directory, edge)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, "#{JSON.pretty_generate(document)}\n")
+        path
+      end
+
+      # Reads every committed approval of a domain.
+      #
+      # @param directory [String] the domain's bluebook directory
+      # @return [Array<Hash{String => Object}>] each parsed file; one that is not JSON is skipped,
+      #   since a file that cannot be read approves nothing
+      def read_all(directory)
+        Dir[File.join(directory, "translations", "*#{EXTENSION}")].filter_map do |path|
+          parsed = JSON.parse(File.read(path))
+          parsed if parsed.is_a?(Hash)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      # The committed approval that lets an edge mint, if there is one.
+      #
+      # @param directory [String, nil] the domain's bluebook directory
+      # @param edge [Bluebook::Translation] the parsed translation edge
+      # @param host_version [String] the running host's release
+      # @return [Hash{String => Object}, nil] an approval whose digest is the edge's, that names
+      #   who approved it and when, and whose rehearsal passed on a compatible host when the edge
+      #   needs one; nil when none applies
+      def applicable(directory, edge, host_version: HOST_RELEASE)
+        return unless directory
+
+        digest = edge_digest(edge)
+        read_all(directory).find do |approval|
+          approval["edge_digest"] == digest && attributed?(approval) &&
+            (!needs_rehearsal?(edge) ||
+              (rehearsed?(approval["rehearsal"]) && host_compatible?(approval["rehearsal"], host_version)))
+        end
+      end
+
+      # Why a committed approval that covers the edge was still not applied, when the only thing
+      # wrong is the host it was rehearsed on.
+      #
+      # @param directory [String, nil] the domain's bluebook directory
+      # @param edge [Bluebook::Translation] the parsed translation edge
+      # @param host_version [String] the running host's release
+      # @return [String, nil] `host_refusal`'s text, or nil when no such approval exists
+      def host_mismatch(directory, edge, host_version: HOST_RELEASE)
+        return unless directory && needs_rehearsal?(edge)
+
+        digest = edge_digest(edge)
+        stale = read_all(directory).find do |approval|
+          approval["edge_digest"] == digest && attributed?(approval) && rehearsed?(approval["rehearsal"]) &&
+            !host_compatible?(approval["rehearsal"], host_version)
+        end
+        host_refusal(stale["rehearsal"], host_version) if stale
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/plugins/era/translation/audit/approval_digest.rb

@@ -4,7 +4,7 @@ require_relative "../../../../../../projector/exporter"
 module Hecks
   module Translation
     module Audit
-      # The human gate: a compute edge cannot mint until `bin/translation_audit --approve`
+      # The human gate: a compute edge cannot mint until `hecks audit_translation --approve`
       # binds an approval to the edge's content digest and the journal's ordinal at review.
       module ApprovalDigest
         # Fingerprints a parsed translation edge, so an approval lapses when the edge's