hecks 2.5.1 → 2.7.0

data/lib/hecks/mcp_stdio_guard.rb

@@ -0,0 +1,160 @@
+require "socket"
+
+module Hecks
+  # The startup gate for the stdio MCP servers in `bin/` (`hecks_mcp_door`,
+  # `hecks_query_ir_mcp`): it refuses to run when the process was set up to
+  # speak to anything but a local parent, and it says on stderr what the
+  # process does and does not protect.
+  #
+  # ## Why a gate and not a comment
+  #
+  # Both servers have no authentication. What keeps a stranger away from
+  # them is that only a process that can spawn them can write to their
+  # stdin. That holds until someone wraps one in `socat TCP-LISTEN:... EXEC:`
+  # or an `inetd`-style listener, which hands the process a network socket
+  # as stdin/stdout without changing a line of the server. The gate turns
+  # that setup into a refusal at startup instead of an exposure nobody
+  # noticed.
+  #
+  # ## What it checks
+  #
+  # - **Arguments** — none, except `--stdio`. A `--port` or `--http` flag is
+  #   refused rather than ignored, so a caller that believes it started a
+  #   network server finds out immediately.
+  # - **Environment** — no `HECKS_MCP_*` variable except
+  #   `HECKS_MCP_TRANSPORT=stdio`. The servers take no configuration, so an
+  #   unknown option in that namespace fails closed.
+  # - **Descriptors** — stdin and stdout must not be internet-protocol sockets
+  #   (`AF_INET` or `AF_INET6`). A pipe, a file, a terminal and a Unix-domain socket all pass;
+  #   the last matters because some MCP clients spawn servers over a
+  #   `socketpair`, which is local to the machine.
+  #
+  # ## What it does not do
+  #
+  # It does not authenticate anyone and it cannot see a proxy that copies
+  # bytes from a network socket into an ordinary pipe. It closes the
+  # configurations that announce themselves; the ADR on MCP authentication
+  # (`docs/decisions/0062-mcp-servers-need-real-authentication-before-any-network-transport.md`)
+  # covers what a network transport would need.
+  module McpStdioGuard
+    ACCEPTED_ARGS = %w[--stdio].freeze
+    ENV_PREFIX    = "HECKS_MCP_".freeze
+    ACCEPTED_ENV  = { "HECKS_MCP_TRANSPORT" => "stdio" }.freeze
+    EXIT_STATUS   = 2
+
+    # The lines every stdio server prints, ahead of its own notes.
+    COMMON_NOTES = [
+      "stdio only. This server has no authentication and must not be exposed over a network.",
+      "Whoever can write to this process's stdin can make every call it accepts."
+    ].freeze
+
+    module_function
+
+    # Lists every reason this process should not start as a stdio server.
+    #
+    # @param argv [Array<String>] the command-line arguments
+    # @param env [Hash{String => String}] the process environment
+    # @param stdin [IO] the stream requests arrive on
+    # @param stdout [IO] the stream responses leave on
+    # @return [Array<String>] one message per violation; empty when the process is
+    #   set up for stdio
+    def violations(argv: ARGV, env: ENV, stdin: $stdin, stdout: $stdout)
+      argument_violations(argv) + environment_violations(env) + descriptor_violations(stdin, stdout)
+    end
+
+    # Builds the warning printed at startup.
+    #
+    # @param server [String] the server's name, used as the line prefix
+    # @param notes [Array<String>] server-specific lines added after `COMMON_NOTES`
+    # @return [Array<String>] the banner lines, each prefixed with `server`
+    def banner(server:, notes: [])
+      (COMMON_NOTES + notes).map { |line| "#{server}: #{line}" }
+    end
+
+    # Refuses to continue on a non-stdio setup.
+    #
+    # A server calls this before it requires anything heavy, so a misconfigured start
+    # fails in milliseconds and before any protocol byte is answered. Everything goes
+    # to `stderr`: stdout carries the MCP protocol, and one stray line there corrupts
+    # the client's framing.
+    #
+    # @param server [String] the server's name, used as the line prefix
+    # @param argv [Array<String>] the command-line arguments
+    # @param env [Hash{String => String}] the process environment
+    # @param stdin [IO] the stream requests arrive on
+    # @param stdout [IO] the stream responses leave on
+    # @param stderr [IO] where the refusal is written
+    # @return [void]
+    # @raise [SystemExit] with status `EXIT_STATUS` when `violations` is not empty
+    def enforce_stdio!(server:, argv: ARGV, env: ENV, stdin: $stdin, stdout: $stdout, stderr: $stderr)
+      found = violations(argv: argv, env: env, stdin: stdin, stdout: stdout)
+      refuse!(server, found, stderr) unless found.empty?
+    end
+
+    # Prints the startup warning to `stderr`, never to stdout.
+    #
+    # @param server [String] the server's name, used as the line prefix
+    # @param notes [Array<String>] server-specific warning lines
+    # @param stderr [IO] where the warning is written
+    # @return [void]
+    def warn!(server:, notes: [], stderr: $stderr)
+      banner(server: server, notes: notes).each { |line| stderr.puts(line) }
+    end
+
+    # Enforces stdio, then prints the warning.
+    #
+    # @param server [String] the server's name, used as the line prefix
+    # @param notes [Array<String>] server-specific warning lines
+    # @param stderr [IO] where the refusal or the warning is written
+    # @param checks [Hash{Symbol => Object}] `argv:`, `env:`, `stdin:` and `stdout:`, as
+    #   for `enforce_stdio!`
+    # @return [void]
+    # @raise [SystemExit] with status `EXIT_STATUS` when the setup is not stdio
+    def start!(server:, notes: [], stderr: $stderr, **checks)
+      enforce_stdio!(server: server, stderr: stderr, **checks)
+      warn!(server: server, notes: notes, stderr: stderr)
+    end
+
+    # @api private
+    def refuse!(server, found, stderr)
+      found.each { |message| stderr.puts("#{server}: refusing to start: #{message}") }
+      stderr.puts("#{server}: this server speaks MCP over stdio only.")
+      exit(EXIT_STATUS)
+    end
+
+    # @api private
+    def argument_violations(argv)
+      (argv - ACCEPTED_ARGS).map do |arg|
+        "argument #{arg.inspect} is not accepted (only #{ACCEPTED_ARGS.join(', ')}); network options are refused, not ignored"
+      end
+    end
+
+    # @api private
+    def environment_violations(env)
+      env.select { |name, value| name.start_with?(ENV_PREFIX) && ACCEPTED_ENV[name] != value }.map do |name, value|
+        "environment #{name}=#{value.inspect} is not accepted; the servers take no #{ENV_PREFIX}* options " \
+          "except #{ACCEPTED_ENV.map { |k, v| "#{k}=#{v}" }.join(', ')}"
+      end
+    end
+
+    # @api private
+    def descriptor_violations(stdin, stdout)
+      { "stdin" => stdin, "stdout" => stdout }.select { |_, io| ip_socket?(io) }.map do |label, _|
+        "#{label} is a network (IP) socket, so this process is being served over a network"
+      end
+    end
+
+    # A socket whose address cannot be read is refused: it cannot be shown to be local.
+    #
+    # @api private
+    def ip_socket?(io)
+      return false unless io.stat.socket?
+
+      socket = Socket.for_fd(io.fileno)
+      socket.autoclose = false # the descriptor belongs to `io`
+      socket.local_address.ip?
+    rescue SystemCallError, IOError
+      true
+    end
+  end
+end

data/lib/hecks/ports/key_vault.rb

@@ -47,7 +47,7 @@ module Hecks
       #
       # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
       #   dispatcher both the lookup query and the `Shred` dispatch run through
-      # @param domain [String] the subject's own domain FQN, e.g. `"Lifeadelics::Registration"`
+      # @param domain [String] the subject's own domain FQN, e.g. `"Site::Registration"`
       # @param subject_id [String] the data subject to erase
       # @return [Boolean] true when a live key was found and shredded by this call; false
       #   when no `SubjectKey` record exists for this subject, or it was already shredded

data/lib/hecks/ports/persistence/binding_policy.rb

@@ -15,6 +15,13 @@ module Hecks
         # A domain with no hecksagon gets the default in-memory bind. A domain that has one
         # must bind the aggregate exactly once without a role.
         #
+        # A `default_adapter` a world declares (`Registry#default_adapter_for` — the
+        # chapter's own world, else the project's) stands in wherever the hecksagon binds
+        # nothing for the aggregate, and replaces the in-memory fallback for a domain
+        # with no hecksagon. It is never consulted once the hecksagon binds the aggregate
+        # or declares a domain-level default of its own, so an explicit chapter decision
+        # always wins.
+        #
         # @param registry [Runtime::Registry] the registry holding the domain's hecksagon
         # @param domain [String, Symbol] name of the domain the aggregate belongs to
         # @param aggregate [Bluebook::Aggregate] the aggregate whose binding is wanted
@@ -23,10 +30,12 @@ module Hecks
         # @raise [Runtime::WiringError] if the hecksagon has no `persisted_by` bind for the
         #   aggregate, more or fewer than one bind without a role, or any bind with a role
         def resolve(registry, domain, aggregate)
-          hexagon = registry.hecksagon(domain)
-          return default_binding(aggregate) unless hexagon
+          hexagon  = registry.hecksagon(domain)
+          declared = registry.default_adapter_for(domain)
+          return default_binding(aggregate, declared || DEFAULT_ADAPTER) unless hexagon
 
           bindings = hexagon.binds_for(aggregate.hecks_name, VERB)
+          bindings = [default_binding(aggregate, declared)] if bindings.empty? && declared
           raise missing_binding(domain, aggregate) if bindings.empty?
 
           authoritative = bindings.select { |bind| bind.role.nil? || bind.role.empty? }
@@ -39,9 +48,11 @@ module Hecks
         # Builds the bind an aggregate gets when its domain declares no hecksagon.
         #
         # @param aggregate [Bluebook::Aggregate] the aggregate to bind
-        # @return [Bluebook::Bind] a roleless `persisted_by` bind to `DEFAULT_ADAPTER`
-        def default_binding(aggregate)
-          Bluebook::Bind.new(aggregate: aggregate.hecks_name, verb: VERB, adapter: DEFAULT_ADAPTER)
+        # @param adapter [String] the adapter to bind it to; the framework's in-memory
+        #   default unless a world declared one
+        # @return [Bluebook::Bind] a roleless `persisted_by` bind to `adapter`
+        def default_binding(aggregate, adapter = DEFAULT_ADAPTER)
+          Bluebook::Bind.new(aggregate: aggregate.hecks_name, verb: VERB, adapter: adapter)
         end
 
         # Builds, without raising, the error for an aggregate a hecksagon leaves unbound.

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

@@ -4,6 +4,7 @@ require_relative "lineage"
 require_relative "../../../../naming"
 require_relative "../../../../framework"
 require_relative "../../../../runtime/registry"
+require_relative "expected_era"
 
 module Hecks
   module Runtime
@@ -295,7 +296,7 @@ module Hecks
                 "it could be found (checked #{directory.inspect} and the framework registry)"
         end
 
-        settings = registry.world(bluebook.name)&.for_binding(Ports::Persistence::VERB, adapter_name) || {}
+        settings = registry.binding_settings(bluebook.name, Ports::Persistence::VERB, adapter_name)
         registry.adapter_class(adapter_name).era_check!(
           registry: registry, bluebook: bluebook, current_text: current_text, settings: settings,
           directory: directory

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

@@ -0,0 +1,132 @@
+require "json"
+require "net/http"
+require "uri"
+
+module Hecks
+  module Runtime
+    module EraCheck
+      # The read side of the era gate, for a deploy operator rather than a boot:
+      # asks a running host which era it reports at `GET /version` and compares
+      # it with an allow-list file of the eras that should be running.
+      #
+      # `EraCheck.check!` decides at boot, against the store, whether a host may
+      # run on an era. This answers the question after a roll, from outside:
+      # did the host that came up report an era the operator expects? The two
+      # never share state. The host's own `GET /version` document
+      # (`rust/host/src/server.rs`, `version_body`) is the only input, so a
+      # rollback to an older image, or a fork of the journal back onto an older
+      # era, shows up here as an era missing from the list.
+      #
+      # ## The allow-list file
+      #
+      # One era id per line. Blank lines and lines starting with `#` are
+      # ignored, and so is a trailing ` # comment`. A file that lists no era
+      # means "only check that the host reports one", so a first roll can be
+      # checked before any era id is known. The generated `expected-era` file
+      # (`Deploy::Scripts`) has this shape.
+      #
+      # `bin/check_era` is the command-line wrapper.
+      module ExpectedEra
+        # The host could not be reached, or did not answer with a `200`.
+        class Unreachable < StandardError; end
+
+        # The host answered, but not with a `/version` document carrying an era.
+        class BadResponse < StandardError; end
+
+        # What a comparison concluded.
+        #
+        # @!attribute [r] status
+        #   @return [Symbol] `:match`, `:unlisted` (no era on the list, one reported) or `:mismatch`
+        # @!attribute [r] era
+        #   @return [String] the era the host reported
+        # @!attribute [r] allowed
+        #   @return [Array<String>] the eras the list accepts
+        Verdict = Struct.new(:status, :era, :allowed) do
+          # Tells whether the roll is acceptable.
+          #
+          # @return [Boolean] true unless the reported era is off the list
+          def ok? = status != :mismatch
+        end
+
+        module_function
+
+        # Reads the eras out of an allow-list file's text.
+        #
+        # @param text [String] the file's contents
+        # @return [Array<String>] the era ids in file order, without comments or blanks
+        def parse(text)
+          text.each_line.filter_map do |line|
+            entry = line.strip.sub(/\s+#.*\z/, "")
+            entry unless entry.empty? || entry.start_with?("#")
+          end
+        end
+
+        # Builds the `/version` URL from what an operator gave.
+        #
+        # @param url [String] a host's base URL, or its `/version` URL itself
+        # @return [String] the URL to request
+        def version_url(url)
+          base = url.to_s.chomp("/")
+          base.end_with?("/version") ? base : "#{base}/version"
+        end
+
+        # Asks a host which era it reports.
+        #
+        # @param url [String] the host's base URL, or its `/version` URL
+        # @param timeout [Numeric] seconds allowed for connecting and for reading
+        # @return [String] the `era` the host's `/version` document carries
+        # @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)
+          response = get(version_url(url), timeout)
+          raise Unreachable, "#{version_url(url)} answered #{response.code}" unless response.code == "200"
+
+          era = JSON.parse(response.body)["era"]
+          raise BadResponse, "#{version_url(url)} carries no era" unless era.is_a?(String) && !era.empty?
+
+          era
+        rescue JSON::ParserError, TypeError
+          raise BadResponse, "#{version_url(url)} did not answer a JSON version document"
+        end
+
+        # Compares a reported era with an allow-list.
+        #
+        # @param era [String] the era the host reported
+        # @param allowed [Array<String>] the eras the list accepts; empty accepts any
+        # @return [Verdict] `:unlisted` when the list is empty, else `:match` or `:mismatch`
+        def verdict(era, allowed)
+          status = if allowed.empty? then :unlisted
+                   elsif allowed.include?(era) then :match
+                   else :mismatch
+                   end
+          Verdict.new(status, era, allowed)
+        end
+
+        # Fetches the host's era and compares it with an allow-list file.
+        #
+        # @param url [String] the host's base URL, or its `/version` URL
+        # @param file [String] path of the allow-list file
+        # @param timeout [Numeric] seconds allowed for connecting and for reading
+        # @return [Verdict] the comparison
+        # @raise [Errno::ENOENT] if the allow-list file does not exist
+        # @raise [Unreachable] see `fetch_era`
+        # @raise [BadResponse] see `fetch_era`
+        def check(url, file, timeout: 10)
+          allowed = parse(File.read(file))
+          verdict(fetch_era(url, timeout: timeout), allowed)
+        end
+
+        def get(url, timeout)
+          uri = URI.parse(url)
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                              open_timeout: timeout, read_timeout: timeout) do |http|
+            http.request(Net::HTTP::Get.new(uri.request_uri, "Accept" => "application/json"))
+          end
+        rescue SystemCallError, SocketError, Timeout::Error, IOError, URI::InvalidURIError => e
+          raise Unreachable, "#{url} could not be reached: #{e.message}"
+        end
+        private_class_method :get
+      end
+    end
+  end
+end

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

@@ -159,7 +159,7 @@ module Hecks
           # aware, same as `apply_drop` above (`apply_backfill`'s own
           # header) — a bare name was the only shape this ever needed
           # until a value object gained new required members with zero
-          # source data of their own (found live: lifeadelics' Attendee
+          # source data of their own (found live: a client site's Attendee
           # redesign, commit 4326dcd).
           @backfills.each { |backfill| apply_backfill(state, backfill) }
           Entry.new(operation: entry.operation, id: entry.id, state: state, mirrors: entry.mirrors)

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

@@ -64,7 +64,7 @@ module Hecks
         # real, live gap for any new required value-object member with no
         # source data at all — `compute` cannot fill it either, since its
         # own guard requires a real, already-present field to consume
-        # (found live: lifeadelics' Attendee redesign, commit 4326dcd,
+        # (found live: a client site's Attendee redesign, commit 4326dcd,
         # needed exactly this and had nothing that worked).
         declared.backfills.each do |backfill|
           expression = compile_backfill(expression, backfill)

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

@@ -12,10 +12,13 @@ module Hecks
     module Persistence
       module Plugins
         # ADR 0033 — requiring this file is installing the plugin. Nothing in
-        # Hecks core requires it; an app that binds `PostgresEra`, or wants
-        # schema-translation support at all, requires it explicitly — the
-        # same shape every adapter-specific spec fixture already uses to
-        # load one particular `.adapter` file rather than all of them.
+        # Hecks core requires it. A boot loads it on demand for a domain that
+        # binds `PostgresEra` (`Runtime::Loader.load_bound_adapters!` resolves the
+        # adapter, which autoloads this file, before the gates are collected). An
+        # app that wants schema-translation support without binding `PostgresEra`
+        # requires it explicitly, the same shape every adapter-specific spec
+        # fixture already uses to load one particular `.adapter` file rather than
+        # all of them.
         module Era
           module_function
 

data/lib/hecks/ports/persistence/postgres_dump/connection.rb

@@ -0,0 +1,73 @@
+require "uri"
+
+module Hecks
+  module Ports
+    module Persistence
+      class PostgresDump
+        # A Postgres connection URL, split so a password reaches the tools run
+        # against it through their environment and never on a command line, where
+        # any user of the machine can read it from the process list.
+        class Connection
+          # @param url [String] a `postgres://` or `postgresql://` URL
+          # @raise [PostgresDump::Error] if `url` is not a Postgres URL
+          def initialize(url)
+            @uri = URI.parse(url)
+            raise Error, "not a postgres URL" unless %w[postgres postgresql].include?(@uri.scheme)
+          end
+
+          # Names the database the URL points at.
+          #
+          # @return [String] the database name, empty when the URL names none
+          def database
+            @uri.path.to_s.delete_prefix("/")
+          end
+
+          # Points the same server and credentials at another database.
+          #
+          # @param name [String] the database to connect to instead
+          # @return [Connection] a new connection; this one is unchanged
+          def with_database(name)
+            copy = @uri.dup
+            copy.path = "/#{name}"
+            self.class.new(copy.to_s)
+          end
+
+          # Lists the connection settings the URL carries, in `PG.connect` keyword form.
+          #
+          # @return [Hash{Symbol => String, Integer}] `host`, `port`, `user`, `password`,
+          #   `dbname` and `sslmode`, each only when the URL gives one; the user and password
+          #   are percent-decoded
+          def settings
+            {
+              host: (@uri.host unless @uri.host.to_s.empty?), port: @uri.port,
+              user: decode(@uri.user), password: decode(@uri.password),
+              dbname: (database unless database.empty?), sslmode: URI.decode_www_form(@uri.query.to_s).to_h["sslmode"]
+            }.compact
+          end
+
+          # Builds the libpq environment variables for a child process.
+          #
+          # @return [Hash{String => String}] `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`,
+          #   `PGDATABASE` and `PGSSLMODE`, each only when `settings` has the matching key
+          def env
+            settings.to_h { |key, value| ["PG#{key.to_s.sub('dbname', 'database').upcase}", value.to_s] }
+          end
+
+          # Opens a connection with the `pg` gem.
+          #
+          # @return [PG::Connection] an open connection; the caller closes it
+          def connect
+            require "pg"
+            PG.connect(**settings)
+          end
+
+          private
+
+          def decode(value)
+            value && URI.decode_www_form_component(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/postgres_dump.rb

@@ -0,0 +1,125 @@
+require "open3"
+require "securerandom"
+require_relative "postgres_dump/connection"
+
+module Hecks
+  module Ports
+    module Persistence
+      # Dumps one schema of a Postgres database and proves the dump restores.
+      #
+      # ## What the proof is
+      #
+      # A dump nobody has restored is a hope. After `pg_dump` writes the file,
+      # the dump is restored into a scratch database (on the source server, or on a
+      # separate `verify_url` server such as the one the dump will be loaded
+      # into) and every table's row count is compared with the source. That shows
+      # the dump is complete and loadable. It does not re-derive current state
+      # from an event journal, so a caller who needs that proves it separately.
+      #
+      # ## Credentials
+      #
+      # URLs are split by `Connection`: the password travels in the child
+      # process's environment, never in `argv`.
+      #
+      # ## Requirements
+      #
+      # The `pg` gem, and `pg_dump` and `pg_restore` on `PATH` at a version no older
+      # than the server's. Neither the gem nor the tools are a dependency of
+      # hecks; nothing here loads until a dump is asked for.
+      class PostgresDump
+        # Raised for a refusal or a failed tool.
+        class Error < StandardError; end
+
+        # What a verified dump holds.
+        #
+        # @!attribute [r] tables
+        #   @return [Hash{String => Integer}] row count of every table in the schema, by name
+        Result = Struct.new(:tables, keyword_init: true)
+
+        # @param url [String] the source database's `postgres://` URL
+        # @param schema [String] the schema to dump, a plain identifier
+        # @param verify_url [String, nil] the server to restore into for the proof; the source
+        #   server when nil
+        # @raise [Error] if `schema` is not a plain identifier or a URL is not a Postgres URL
+        def initialize(url:, schema:, verify_url: nil)
+          raise Error, "schema #{schema.inspect} is not a plain identifier" unless schema.to_s.match?(/\A[a-z_][a-z0-9_]*\z/i)
+
+          @schema = schema
+          @source = Connection.new(url)
+          @verify = Connection.new(verify_url || url)
+        end
+
+        # Writes a custom-format dump of the schema and proves it restores.
+        #
+        # @param dest [String] the file to write
+        # @return [Result] the verified row counts
+        # @raise [Error] if the schema has no tables, a tool fails, the database refuses, or
+        #   the restored counts differ from the source's
+        def call(dest)
+          require "pg"
+          raise Error, "schema #{@schema} has no tables in #{@source.database}" if counting(@source) { |db| counts(db) }.empty?
+
+          run("pg_dump", @source, "--format=custom", "--no-owner", "--no-privileges", "--schema=#{@schema}", "--file=#{dest}")
+          expected = counting(@source) { |db| counts(db) }
+          verify_restore(dest, expected)
+          Result.new(tables: expected)
+        rescue PG::Error => e
+          raise Error, "database error (#{e.class}): #{e.message.lines.first.to_s.strip}"
+        end
+
+        private
+
+        def verify_restore(dump, expected)
+          scratch = "dump_verify_#{Process.pid}_#{SecureRandom.hex(3)}"
+          counting(@verify) do |admin|
+            admin.exec("CREATE DATABASE #{admin.quote_ident(scratch)}")
+            begin
+              target = @verify.with_database(scratch)
+              run("pg_restore", target, "--no-owner", "--no-privileges", "--exit-on-error", "--dbname=#{scratch}", dump)
+              actual = counting(target) { |db| counts(db) }
+              raise Error, mismatch(expected, actual) unless actual == expected
+            ensure
+              drop(admin, scratch)
+            end
+          end
+        end
+
+        def counting(connection)
+          db = connection.connect
+          yield db
+        ensure
+          db&.close
+        end
+
+        def counts(db)
+          names = db.exec_params("SELECT table_name FROM information_schema.tables " \
+                                 "WHERE table_schema = $1 AND table_type = 'BASE TABLE' ORDER BY 1", [@schema])
+                    .map { |row| row["table_name"] }
+          names.to_h do |name|
+            [name, db.exec("SELECT count(*) FROM #{db.quote_ident(@schema)}.#{db.quote_ident(name)}").getvalue(0, 0).to_i]
+          end
+        end
+
+        def mismatch(expected, actual)
+          differing = (expected.keys | actual.keys).reject { |name| expected[name] == actual[name] }
+          detail = differing.map { |name| "#{name} (source #{expected[name].inspect}, restored #{actual[name].inspect})" }
+          "the restored dump disagrees with the source for #{detail.join(', ')}; " \
+            "if the database took writes during the dump, dump it again"
+        end
+
+        def drop(admin, scratch)
+          admin.exec("DROP DATABASE IF EXISTS #{admin.quote_ident(scratch)} WITH (FORCE)")
+        rescue PG::Error => e
+          warn "could not drop scratch database #{scratch} (#{e.class}); drop it by hand"
+        end
+
+        def run(tool, connection, *)
+          _out, err, status = Open3.capture3(connection.env, tool, *)
+          raise Error, "#{tool} failed: #{err.lines.first(3).join.strip}" unless status.success?
+        rescue Errno::ENOENT
+          raise Error, "#{tool} is not on PATH"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/ports/persistence/repository_factory.rb

@@ -30,8 +30,8 @@ module Hecks
         #   lacks `append`, `project` or `entries`
         def build(registry, domain, aggregate, bind, recover: true, settings_verb: VERB)
           registry.check_verb(bind)
-          settings = (registry.world(domain)&.for_binding(settings_verb, bind.adapter) || {})
-                     .reject { |key, _| key.to_sym == :role }
+          settings = registry.binding_settings(domain, settings_verb, bind.adapter)
+                             .reject { |key, _| key.to_sym == :role }
           registry.check_settings(bind, settings)
           # The domain, the resolved era, and (for an old checkout) the era
           # that superseded it ride along after the declared-settings

data/lib/hecks/ports/persistence.rb

@@ -17,6 +17,10 @@ require_relative "persistence/remote_runtime"
 require_relative "persistence/null_saga_store"
 require_relative "persistence/state_codec"
 
+# Loaded on first mention: nothing about a domain's own boot needs the dump
+# tooling, and it wants the optional `pg` gem.
+Hecks::Ports::Persistence.autoload(:PostgresDump, File.join(__dir__, "persistence/postgres_dump"))
+
 module Hecks
   module Ports
     # Reopened once `BindingPolicy`/`RepositoryFactory` (required above) are