hecks 3.10.0 → 3.11.0

data/lib/hecks/hecks/adapters/cost_explorer.rb

@@ -16,6 +16,9 @@ module Hecks
     # it, a span with no complete day, or a failed `aws` call is refused with a reason, which the
     # runtime records on the check.
     class CostExplorer
+      # Raised when the budget is exceeded or Cost Explorer cannot be read.
+      class Error < RuntimeError; end
+
       # Days in an average month, for scaling a daily mean to a monthly rate.
       DAYS_IN_MONTH = 30.4375
 
@@ -35,17 +38,17 @@ module Hecks
       #   first day to count (`YYYY-MM-DD`), each a value object or a plain value
       # @return [Hash{Symbol => Hash}] `report:` the rate against the budget, the shape
       #   `CostCheck.Pass` takes
-      # @raise [RuntimeError] when no complete day has passed since `since`, `aws` fails, or the
+      # @raise [Error] when no complete day has passed since `since`, `aws` fails, or the
       #   rate is over the budget
       def measure(**held)
         budget = Integer(plain(held[:budget]))
         first = Date.iso8601(plain(held[:since]).to_s)
         last = today
-        raise "no complete day since #{first}; today (#{last}) is still being billed" if first >= last
+        raise Error, "no complete day since #{first}; today (#{last}) is still being billed" if first >= last
 
         days = daily_costs(first, last)
         line = report_line(first, last, days, budget)
-        raise "over budget: #{line}" if monthly_rate(days) > budget
+        raise Error, "over budget: #{line}" if monthly_rate(days) > budget
 
         { report: { value: line } }
       end
@@ -62,10 +65,10 @@ module Hecks
           "--granularity", "DAILY", "--metrics", "UnblendedCost",
           "--group-by", "Type=DIMENSION,Key=SERVICE", "--output", "json"
         )
-        raise "aws ce get-cost-and-usage failed: #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+        raise Error, "aws ce get-cost-and-usage failed: #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
 
         rows = JSON.parse(out).fetch("ResultsByTime")
-        raise "Cost Explorer returned no days for #{first}..#{last}" if rows.empty?
+        raise Error, "Cost Explorer returned no days for #{first}..#{last}" if rows.empty?
 
         rows.to_h { |row| [row.dig("TimePeriod", "Start"), by_service(row)] }
       end

data/lib/hecks/hecks/adapters/deploy_toolchain/statuses.rb

@@ -26,7 +26,8 @@ module Hecks
 
         # What each status of `deploy-box.sh` means, for the reason a refusal gives.
         BOX_STATUS = { 40 => "the box stack has no instance", 41 => "the roll did not succeed on the box",
-                       42 => "the box is not healthy after the roll" }.freeze
+                       42 => "the box is not healthy after the roll",
+                       43 => "the database has no usable restore anchor (backups unreadable or kept too few days)" }.freeze
 
         # What each status of `deploy-service.sh` means; it ends with the box roll's own statuses.
         SERVICE_STATUS = { 2 => "unknown service", 30 => "the existing tag is not in ECR",

data/lib/hecks/hecks/adapters/finding_github.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "open3"
+require_relative "../../indifferent_key"
 
 module Hecks
   module Adapters
@@ -12,6 +13,9 @@ module Hecks
     # and the runtime records the refusal on the finding. An ask that needs the issue before one
     # was opened is refused the same way, so a finding never blocks on GitHub.
     class FindingGithub
+      # Raised when `gh` cannot file or find the finding's issue.
+      class Error < RuntimeError; end
+
       # The environment variable that names the repository when no setting does.
       REPOSITORY_VARIABLE = "HECKS_FINDINGS_REPO"
 
@@ -27,12 +31,12 @@ module Hecks
       # @param held [Hash] the finding's fields; `title` and `body` are value objects or strings
       # @return [Hash{Symbol => Hash}] `issue_number:` of the new issue, the shape
       #   `Finding.RecordIssue` takes
-      # @raise [RuntimeError] when no repository is named, `gh` exits non-zero, or prints no
+      # @raise [Error] when no repository is named, `gh` exits non-zero, or prints no
       #   issue URL
       def open_issue(**held)
         out = gh("issue", "create", "--title", plain(held[:title]).to_s, "--body", plain(held[:body]).to_s)
         number = out.lines.last.to_s.strip[%r{/issues/(\d+)\z}, 1]
-        raise "gh issue create printed no issue URL: #{out.strip.inspect}" unless number
+        raise Error, "gh issue create printed no issue URL: #{out.strip.inspect}" unless number
 
         { issue_number: { value: number.to_i } }
       end
@@ -82,7 +86,10 @@ module Hecks
 
       def gh(*arguments)
         out, err, status = Open3.capture3("gh", *arguments, "--repo", repository)
-        raise "gh #{arguments.first(2).join(" ")} failed — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+        unless status.success?
+          raise Error,
+                "gh #{arguments.first(2).join(" ")} failed — #{err.strip.empty? ? out.strip : err.strip}"
+        end
 
         out
       end
@@ -91,12 +98,12 @@ module Hecks
         name = @repository || ENV.fetch(REPOSITORY_VARIABLE, nil)
         return name unless name.to_s.strip.empty?
 
-        raise "no repository named: set the `repository` setting or #{REPOSITORY_VARIABLE} to owner/name"
+        raise Error, "no repository named: set the `repository` setting or #{REPOSITORY_VARIABLE} to owner/name"
       end
 
       def issue(held)
         number = plain(held[:issue_number])
-        raise "the finding has no GitHub issue yet" if number.to_s.empty?
+        raise Error, "the finding has no GitHub issue yet" if number.to_s.empty?
 
         number.to_s
       end
@@ -107,7 +114,7 @@ module Hecks
       def plain(field)
         return field unless field.is_a?(Hash)
 
-        field.key?(:value) ? field[:value] : field["value"]
+        IndifferentKey.read(field, :value)
       end
     end
   end

data/lib/hecks/hecks/adapters/first_admin.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../doors/json_door"
+require_relative "../../adapters/driving/json"
 
 module Hecks
   module Adapters
@@ -87,7 +87,7 @@ module Hecks
         %i[admit grant people].to_h { |key| [key, provider.provided_verb(Bluebook::Capabilities::MEMBERSHIP, key)] }
       end
 
-      def rows(verb) = @runtime.query(verb).map { |row| Doors::JsonDoor.materialize(row) }
+      def rows(verb) = @runtime.query(verb).map { |row| Adapters::Driving::Json.materialize(row) }
 
       # The role a verb's command declares, which the dispatch must assert to be let through.
       def gated_role(provider, verb)

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

@@ -12,6 +12,9 @@ module Hecks
     # 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
+      # Raised when `gh` is missing or refuses a ruleset call.
+      class Error < RuntimeError; end
+
       # 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
@@ -23,7 +26,7 @@ module Hecks
       end
 
       # @return [Array<Hash>] every ruleset of the repository, in full
-      # @raise [RuntimeError] when `gh` is missing or refuses
+      # @raise [Error] 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")}")) }
@@ -37,7 +40,7 @@ module Hecks
       #
       # @param projected [Hash] the ruleset as `Tools::Lanes` projects it
       # @return [Symbol] `:created` or `:updated`
-      # @raise [RuntimeError] when GitHub refuses it
+      # @raise [Error] when GitHub refuses it
       def apply(projected)
         live = named(projected.fetch("name"))
         path = "repos/{owner}/{repo}/rulesets"
@@ -110,7 +113,7 @@ module Hecks
 
       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
+        raise Error, "gh #{args.first(3).join(" ")} failed: #{err.strip.empty? ? out.strip : err.strip}" unless ok
 
         out
       end

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

@@ -174,7 +174,7 @@ module Hecks
         raise Runtime::NotFound, "no domain here, and none named" unless path
         raise Runtime::NotFound, "no such domain #{path.inspect}" unless Dir.exist?(path)
 
-        Hecks.boot(File.expand_path(path), install_doors: false)
+        Hecks.boot(File.expand_path(path), install_driving: false)
       end
 
       def chapter_of(domain, chapter)

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

@@ -23,7 +23,7 @@ module Hecks
         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
+          @registry = Hecks.boot(File.expand_path(path), install_driving: false).registry
           @wanted = aggregates
           @kind = kind
         end

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

@@ -12,17 +12,10 @@ module Hecks
       # 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)
+        # What one audit found: the audited `edge`, how many edges are `leaving` the latest held
+        # era, whether it is `ok`, the `report` text, every refusal (`Aggregate#id: wording`) and
+        # the records as translated (`after`), by aggregate name and id.
+        Finding = Struct.new(:edge, :leaving, :ok, :report, :refusals, :after, keyword_init: true)
 
         # Audits the edge that leaves the latest held era.
         #
@@ -89,14 +82,11 @@ module Hecks
         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"))
+          audits = @held.bluebook.aggregates.map { |aggregate| [aggregate, *verdict_for(aggregate, edge, era, chain)] }
+          lines = audits.flat_map { |aggregate, verdict, records, _| describe(aggregate, edge, verdict, records) }
+          refusals = audits.flat_map { |_, verdict, _, _| verdict.violations }
+          Finding.new(edge: edge, leaving: leaving, ok: refusals.empty?, report: lines.join("\n"),
+                      refusals: refusals, after: audits.to_h { |aggregate, _, _, after| [aggregate.name, after] })
         end
 
         def verdict_for(aggregate, edge, era, chain)
@@ -108,7 +98,7 @@ module Hecks
                    end
           verdict = Translation::Audit.check(aggregate: aggregate, declared: edge.for_aggregate(aggregate.name),
                                              before: before, after: after)
-          [verdict, after.size]
+          [verdict, after.size, after]
         end
 
         def translated(aggregate, era, chain)

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

@@ -22,16 +22,18 @@ module Hecks
         #
         # @param path [String] the domain directory, or the project holding its `bluebook/`
         # @param mode [Symbol] one of `MODES`
+        # @param environment [String, nil] the overlay under `environments/` to load last;
+        #   `HECKS_PROJECT_ENVIRONMENT` when not given
         # @return [HeldDomain] the loaded domain
         # @raise [Runtime::NotFound] if the directory does not exist, declares no bluebook, or
         #   does not load
-        def self.open(path, mode: :translated)
+        def self.open(path, mode: :translated, environment: ENV.fetch("HECKS_PROJECT_ENVIRONMENT", nil))
           raise ArgumentError, "unknown mode #{mode.inspect}" unless MODES.include?(mode)
 
           loading = Ports::Loading.bootstrap
           directory = loading.bluebook_directory(path)
           registry = Runtime::Registry.new(root: File.dirname(directory))
-          load_into(registry, loading, directory, mode)
+          load_into(registry, loading, directory, mode, environment)
           new(registry, directory)
         rescue Errno::ENOENT
           raise Runtime::NotFound, "no such domain #{path.inspect}"
@@ -40,8 +42,7 @@ module Hecks
         end
 
         # @api private
-        def self.load_into(registry, loading, directory, mode)
-          environment = ENV.fetch("HECKS_PROJECT_ENVIRONMENT", nil)
+        def self.load_into(registry, loading, directory, mode, environment)
           Hecks.with_registry(registry) do
             loading.load_library
             loading.load_project(loading.shared_root(nil, directory))
@@ -91,7 +92,29 @@ module Hecks
         # @return [Hash] the settings
         def settings
           declared = registry.binding_settings(bluebook.name, Ports::Persistence::VERB, adapter_name)
-          ENV["HECKS_SCHEMA"] ? declared.merge(schema: ENV["HECKS_SCHEMA"]) : declared
+          declared = declared.merge(schema: ENV["HECKS_SCHEMA"]) if ENV["HECKS_SCHEMA"]
+          declared = declared.merge(schema: @schema) if @schema
+          @database ? declared.merge(database: @database) : declared
+        end
+
+        # Names the schema its journal store is read in, over the world's and `HECKS_SCHEMA`, so a
+        # rehearsal reads the schema it reports.
+        #
+        # @param schema [String] a schema name
+        # @return [HeldDomain] self
+        def read_schema(schema)
+          @schema = schema
+          self
+        end
+
+        # Points the journal store at another database than its world names, so a rehearsal
+        # reads a copy and never the world's own. Every read and write after this reaches it.
+        #
+        # @param database [String] a `postgres://` URL
+        # @return [HeldDomain] self
+        def read_from(database)
+          @database = database
+          self
         end
 
         # The text the era is frozen from: the bluebook source as it stands on disk.

data/lib/hecks/hecks/adapters/local_files.rb

@@ -23,7 +23,7 @@ module Hecks
       # named ones, through `Hecks::CLI::ProjectCli`. A launcher is a generated file that only
       # points at its domain, so an existing one is replaced and nothing else is touched.
       #
-      # @param held [Hash] the `Door` record: `domains` (comma separated paths under the current
+      # @param held [Hash] the `Launch` record: `domains` (comma separated paths under the current
       #   directory; every domain found when absent)
       # @return [Hash{Symbol => Hash}] `output:` one line per launcher written
       # @raise [ConsoleCapture::Failure] when no launcher was written
@@ -45,7 +45,7 @@ module Hecks
       # Nothing is replaced: every file is checked before the first is written, and a directory
       # that already holds a bluebook is refused.
       #
-      # @param held [Hash] the `Door` record: `name`, and optionally `adapter` and `dir`
+      # @param held [Hash] the `Launch` record: `name`, and optionally `adapter` and `dir`
       # @return [Hash{Symbol => Hash}] `output:` the report that was printed
       # @raise [ConsoleCapture::Failure] when the name or adapter is refused, or a file exists
       def scaffold(**held)

data/lib/hecks/hecks/adapters/rehearsal/audit_report.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # What the mint's audit read and what it concluded, as the facts the report holds: how much
+      # was examined by each engine, whether anything was, why not when nothing was, and how the
+      # two engines stood against each other.
+      class AuditReport
+        # The limit a clean verdict carries when no stored row was read.
+        UNAUDITED = "the stored rows"
+
+        # The wording that explains a Rust-only refusal: the Ruby audit's first layer does not hold
+        # a stored value to a closed set, a required field or an undeclared value-object key.
+        RUST_ONLY = "The Rust audit also holds a stored value to its closed set, a required field and an " \
+                    "undeclared value-object key, which the Ruby audit's first layer does not yet: a row " \
+                    "only Rust refuses is that known difference between the engines, not a second finding."
+
+        # @param minting [String] none, first or next
+        # @param edge [Bluebook::Translation, nil] the edge the audit ran through
+        # @param states [Hash{String => Hash}] the translated records the audit read, by aggregate
+        # @param ruby [Array<String>] the Ruby audit's refusals
+        # @param rust [RustAudit::Result] the second engine's answer
+        def initialize(minting:, edge:, states:, ruby:, rust:)
+          @minting = minting
+          @edge = edge
+          @states = states
+          @ruby = ruby
+          @rust = rust
+        end
+
+        # @return [Boolean] whether any stored row was read by the audit
+        def audited? = !@edge.nil? && @minting == "next"
+
+        # @return [Integer] the rows the Ruby audit read
+        def rows = @states.values.sum(&:size)
+
+        # @return [Hash] `audited`, `rows_examined`, `aggregates_examined`, `rust_rows_examined`
+        #   (zero when the second engine did not run, which `parity` says) and the sentence the
+        #   verdict rests on
+        def facts
+          { audited: flag(audited?), rows_examined: count(rows), reason: { value: reason },
+            aggregates_examined: count(aggregates),
+            rust_rows_examined: count(@rust.rows) }
+        end
+
+        # @return [Hash] the Rust engine's standing against the Ruby one, with who refused what
+        def parity
+          return { engine: "rust", status: "not_run", note: @rust.note } unless @rust.ran
+          return { engine: "rust", status: "agree", note: agreed } if ruby_records == rust_records
+
+          { engine: "rust", status: "differ", note: differed }
+        end
+
+        # @return [Array<Hash>] the limit a rehearsal that read nothing carries
+        def limits = audited? ? [] : [{ what: UNAUDITED, why: reason }]
+
+        private
+
+        def flag(value) = { value: value }
+
+        def count(value) = { value: value }
+
+        def reason
+          case @minting
+          when "none" then "no mint is needed at this shape, so no stored row was examined"
+          when "first" then "no era is held, so the first mint holds the shape as it stands and no stored row was examined"
+          else next_reason
+          end
+        end
+
+        def next_reason
+          return "no edge leads the held era to this shape, so no stored row was examined" unless @edge
+
+          "the audit read #{rows} stored row(s) of #{aggregates} aggregate(s) through the edge " \
+            "#{@edge.from} -> #{@edge.to}"
+        end
+
+        def aggregates = @states.count { |_, held| held.any? }
+
+        def ruby_records = records(@ruby)
+
+        def rust_records = records(@rust.violations)
+
+        def records(refusals) = refusals.map { |text| text[/\A[^:]+/] }.uniq.sort
+
+        def agreed = "ruby refused #{ruby_records.size} records, rust #{rust_records.size}; rust read #{@rust.rows} rows"
+
+        def differed
+          rust_only = rust_records - ruby_records
+          ruby_only = ruby_records - rust_records
+          "the engines refused different records: ruby #{ruby_records.size}, rust #{rust_records.size}. " \
+            "#{only("rust", rust_only)}#{only("ruby", ruby_only)}#{known_gap(rust_only)}" \
+            "Both are held against the report: the union is refused."
+        end
+
+        def known_gap(rust_only) = rust_only.empty? ? "" : "#{RUST_ONLY} "
+
+        def only(engine, held)
+          return "" if held.empty?
+
+          "Only #{engine} refused: #{held.first(5).join(", ")}#{", ..." if held.size > 5}. "
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/census.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    module Rehearsal
+      # What a data copy holds for the domain, counted before any audit runs: the eras, the rows
+      # each aggregate's head holds, and the entries and live records of the journal.
+      #
+      # The mint's audit reads the journal (the latest entry of each record), never the head, so
+      # the two counts sit side by side and a divergence between them is visible, not refused.
+      Census = Struct.new(:schema, :source, :present, :eras, :journal_entries, :counts, :elsewhere,
+                          keyword_init: true) do
+        # One aggregate's rows: what its head holds and what the journal's latest entries hold.
+        const_set(:Count, Struct.new(:aggregate, :head, :journal, keyword_init: true))
+
+        # @return [Array<String>] other schemas of the copy that hold a lineage
+        def elsewhere = self[:elsewhere] || []
+
+        # @return [Integer] the rows the heads hold, over every aggregate
+        def head_rows = counts.sum(&:head)
+
+        # @return [Integer] the live records the journal's latest entries hold
+        def journal_rows = counts.sum(&:journal)
+
+        # @return [Boolean] whether the copy holds no row of the domain at all
+        def empty? = head_rows.zero? && journal_rows.zero? && journal_entries.zero?
+
+        # @param domain [String] the domain's name, for the sentence
+        # @return [String] what the copy holds, in words
+        def summary(domain)
+          "the copy holds #{eras} era(s), #{head_rows} head rows and #{journal_rows} journal records for " \
+            "#{domain} in schema #{schema}"
+        end
+
+        # @param domain [String] the domain's name, for the sentence
+        # @return [String] why a copy that holds no row cannot be rehearsed, and what to set
+        def refusal(domain)
+          held = eras.zero? ? "no era and no rows" : "#{eras} era(s) but no rows"
+          where = if source == "memory"
+                    "in the `rows` document"
+                  else
+                    "in schema #{schema}#{" (not in the copy)" unless present}"
+                  end
+          "the copy holds #{held} for domain #{domain} #{where}: #{remedy}#{hint}"
+        end
+
+        # @return [Hash] the report facts, as the `RehearsalRun` commands take them
+        def facts
+          { schema_used: { name: schema, source: source, present: present }, eras_held: { value: eras },
+            journal_entries: { value: journal_entries }, head_rows: { value: head_rows }, census: counts.map(&:to_h) }
+        end
+
+        private
+
+        def where
+          return "in the `rows` document" if source == "memory"
+
+          "in schema #{schema}#{" (not in the copy)" unless present}"
+        end
+
+        def remedy
+          return "name the document that holds the stored records in `rows`" if source == "memory"
+
+          "set the schema in the world file (`rehearsed_by` { schema \"...\" })"
+        end
+
+        def hint = elsewhere.empty? ? "" : "; schemas in this copy that hold a lineage: #{elsewhere.join(", ")}"
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/rehearsal/declaration.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Hecks
+  module Adapters
+    # Everything a rehearsal does on a client's domain: where its data copy comes from, how the
+    # mint's audit is run over it, and what is reported. The two port adapters (`RehearsalStore`
+    # and `RehearsalSubject`) are thin; the work lives here.
+    module Rehearsal
+      # A rehearsal that was not admitted or could not be carried on: the port answers it as a
+      # refusal, which the run keeps as `refusal`.
+      class Refused < StandardError; end
+
+      # What a subject's own `.world` says about the copy of its data, read from its
+      # `rehearsed_by` block and checked before anything is touched.
+      #
+      # A connection is only ever named by an environment variable (`connection_env`); a literal
+      # connection string, user or password in the world is refused, so the file holds no secret.
+      class Declaration
+        KINDS = %w[memory postgres].freeze
+        MODES = %w[empty dump readonly_copy].freeze
+        LITERALS = %i[database url connection password user].freeze
+        LOCAL_HOSTS = [nil, "", "localhost", "127.0.0.1", "::1", "[::1]"].freeze
+
+        NAME = /\A[A-Za-z0-9_-]+\z/
+
+        attr_reader :kind, :mode, :connection_env, :dump, :rows, :drop_after, :allow_remote, :schema, :environment
+
+        # @param world [#for_verb, nil] the subject's world, as the registry holds it
+        # @param directory [String] the domain's bluebook directory, which a relative file is under
+        # @return [Declaration] the checked declaration
+        # @raise [Refused] if the world declares no `rehearsed_by`, or declares it wrongly
+        def self.from_world(world, directory)
+          settings = world&.for_verb("rehearsed_by") || {}
+          raise Refused, "the domain's world declares no `rehearsed_by`: nothing says where its data copy is" if settings.empty?
+
+          new(settings, directory).tap(&:check!)
+        end
+
+        # @param settings [Hash] the block's settings, `adapter:` among them
+        # @param directory [String] where a relative `dump` or `rows` is found
+        def initialize(settings, directory)
+          @kind           = settings[:adapter].to_s.downcase
+          @connection_env = settings[:connection_env]&.to_s
+          @dump           = expand(settings[:dump], directory)
+          @rows           = expand(settings[:rows], directory)
+          @mode           = settings.fetch(:mode) { default_mode }.to_s
+          read_switches(settings)
+        end
+
+        # @return [void]
+        # @raise [Refused] naming what is wrong with the declaration
+        def check!
+          check_names!
+          raise Refused, literal_wording unless @literals.empty?
+
+          kind == "postgres" ? check_postgres! : check_memory!
+        end
+
+        # @return [String] the connection the environment holds
+        # @raise [Refused] if the variable the world names is unset or empty, or names a server
+        #   that is not this machine and the world did not say `allow_remote true`
+        def connection
+          value = ENV.fetch(connection_env, "")
+          raise Refused, "the environment variable #{connection_env} is not set" if value.strip.empty?
+
+          refuse_remote!(value)
+          value
+        end
+
+        private
+
+        def refuse_remote!(value)
+          host = URI.parse(value).host
+          return if allow_remote || LOCAL_HOSTS.include?(host)
+
+          raise Refused, "#{connection_env} names the server #{host.inspect}, which is not this machine: " \
+                         "a rehearsal reads a local copy; say `allow_remote true` in rehearsed_by to point it elsewhere"
+        rescue URI::InvalidURIError
+          nil
+        end
+
+        def read_switches(settings)
+          @drop_after   = settings.fetch(:drop_after, true) != false
+          @allow_remote = settings.fetch(:allow_remote, false) == true
+          @literals     = LITERALS & settings.keys.map(&:to_sym)
+          @schema       = settings[:schema]&.to_s
+          @environment  = settings[:environment]&.to_s
+        end
+
+        def default_mode = dump || rows ? "dump" : "empty"
+
+        def check_names!
+          raise Refused, "rehearsed_by names #{kind.inspect}; the stores are #{KINDS.join(" and ")}" unless KINDS.include?(kind)
+
+          raise Refused, "rehearsed_by mode #{mode.inspect} is not one of #{MODES.join(", ")}" unless MODES.include?(mode)
+
+          check_label!("schema", schema)
+          check_label!("environment", environment)
+        end
+
+        def check_label!(word, value)
+          return if value.nil? || NAME.match?(value)
+
+          raise Refused, "rehearsed_by #{word} #{value.inspect} is not a name (letters, digits, `_`, `-`)"
+        end
+
+        def expand(path, directory)
+          path && File.expand_path(path.to_s, directory)
+        end
+
+        def literal_wording
+          "rehearsed_by holds #{@literals.join(", ")}: name the environment variable in `connection_env`, " \
+            "never the value, so the world file holds no secret"
+        end
+
+        def check_postgres!
+          unless connection_env
+            raise Refused,
+                  "a postgres rehearsal needs `connection_env`, the name of the variable holding the server"
+          end
+          raise Refused, "mode dump needs `dump`, the file to restore" if mode == "dump" && !dump
+        end
+
+        def check_memory!
+          raise Refused, "mode readonly_copy is a postgres mode: a memory store has no copy to read" if mode == "readonly_copy"
+          raise Refused, "mode dump needs `rows`, the JSON file the memory store holds" if mode == "dump" && !rows
+        end
+      end
+    end
+  end
+end