hecks 2.6.0 → 2.7.0

data/lib/hecks/embryonaut_bluebook.rb

@@ -13,10 +13,10 @@ module Hecks
   #
   # This module and its `uses_embryonaut_bluebook`
   # DSL word (hecksagon_builder.rb) were built on a prior commit of this
-  # repo (933d1dd), vendored out to a real consumer (lifeadelics/domain,
+  # repo (933d1dd), vendored out to a real consumer (a client site's domain,
   # for embryonaut_bluebooks/payments), and then lost from this repo's own
   # reachable history — a hard reset or rebase left no branch containing
-  # that commit. The lifeadelics vendor snapshot (a `git archive` of that
+  # that commit. The consumer's vendor snapshot (a `git archive` of that
   # commit, committed into their repo) was the only surviving copy; this
   # file is ported forward from it, checked against current `main`'s own
   # conventions rather than copied wholesale, since the two trees had
@@ -64,7 +64,18 @@ module Hecks
   # => "Payments"), not a separate ledger. A vendored package's directory
   # name and its declared `Hecks.bluebook` name are the one convention
   # this reuses from Framework rather than reinventing.
+  #
+  # ## Vendoring
+  #
+  # `vendor!` is the other direction: it pins a package from a local checkout
+  # of the registry into a consuming project's own `vendor/` tree, and is the
+  # one implementation behind `bin/vendor_bluebook` (see Vendoring and Vendor).
   module EmbryonautBluebook
+    autoload :Lock, File.join(__dir__, "embryonaut_bluebook/lock")
+    autoload :Shape, File.join(__dir__, "embryonaut_bluebook/shape")
+    autoload :Vendor, File.join(__dir__, "embryonaut_bluebook/vendor")
+    autoload :VendorCli, File.join(__dir__, "embryonaut_bluebook/vendor_cli")
+
     # Loads a vendored embryonaut bluebook package's `.bluebook` files, once
     # per registry.
     #
@@ -89,10 +100,25 @@ module Hecks
       if files.empty?
         raise Runtime::WiringError,
               "no vendored embryonaut bluebook named #{name.inspect} at #{dir} — " \
-              "run bin/vendor_embryonaut_bluebooks #{name}"
+              "vendor it with bin/vendor_bluebook #{name}"
       end
 
       files.each { |file| Kernel.load(file) }
     end
+
+    # Pins one package of the registry into a project's `vendor/` tree.
+    #
+    # @param name [String, Symbol] the package's directory name, such as `"payments"`
+    # @param from [String] path of a local checkout of the registry repository
+    # @param ref [String, nil] a release version (`"1.2.0"`), a release tag name, any
+    #   commit-ish, or nil for the newest release
+    # @param root [String] the consuming project's root
+    # @param allow_downgrade [Boolean] whether a release older than the vendored one is allowed
+    # @return [Vendor::Result] the commit, version and storage shape now vendored
+    # @raise [Vendoring::Error] if the source, release or files are unusable, or a
+    #   version-policy refusal applies (see Vendor)
+    def self.vendor!(name, from:, root:, ref: nil, allow_downgrade: false)
+      Vendor.new(name, from: from, root: root, ref: ref, allow_downgrade: allow_downgrade).call
+    end
   end
 end

data/lib/hecks/forms/value_object_shape.rb

@@ -2,7 +2,7 @@ module Hecks
   module Forms
     # The value-object classification every consumer of a resolved VO
     # shape needs, spelled once — `field_shape.rb` (a command's own
-    # form), `ui_schema.rb` (embryonaut_console's table/detail-panel
+    # form), `ui_schema.rb` (the console app's table/detail-panel
     # renderer, a separate app, not this repo), and
     # `adapters/driven/sql_query_builder.rb` (a query's own ORDER BY/
     # where compiler) each grew their own copy of "is this VO money-

data/lib/hecks/framework/bluebook/console_settings.bluebook

@@ -1,5 +1,5 @@
 Hecks.bluebook "ConsoleSettings" do
-  vision "A generic admin console's own curated UI facts — nav, columns, state tones, which rows a detail panel shows — as real dispatched data instead of a hand-rewritten YAML file. A UI opinion the DOMAIN it's pointed at has no way to answer, never a business record; see embryonaut_console's own presentation_config.rb for the fuller story."
+  vision "A generic admin console's own curated UI facts — nav, columns, state tones, which rows a detail panel shows — as real dispatched data instead of a hand-rewritten YAML file. A UI opinion the DOMAIN it's pointed at has no way to answer, never a business record; see the console app's own presentation_config.rb for the fuller story."
   supporting
 
   # A FRAMEWORK MEMBER LIKE IDENTITY/GOVERNANCE — attach with
@@ -7,7 +7,7 @@ Hecks.bluebook "ConsoleSettings" do
   # `.hecksagon`, plus a `Hecks.hecksagon "ConsoleSettings" do ... end`
   # persistence binding (Heki is the common case — a small, local,
   # per-app settings store, no shared database needed). This used to
-  # boot in a SECOND, independent registry (embryonaut_console's own
+  # boot in a SECOND, independent registry (the console app's own
   # console_settings_domain.rb) specifically so no consuming app needed
   # any change at all — that property is real and now given up on
   # purpose, in favor of the one binding mechanism every other
@@ -30,7 +30,7 @@ Hecks.bluebook "ConsoleSettings" do
   # (Overview, below) and every `extra_json`/`identity_extra_json`
   # field throughout this chapter were BOTH originally scoped out on an
   # "confirmed unused in any real presentation.yml" basis that turned
-  # out to be checked against the wrong file — embryonaut_console's own
+  # out to be checked against the wrong file — the console app's own
   # fixture, never this app's actual, live one. Migrating the real file
   # found both very much in use.
 

data/lib/hecks/fuzzing/era_boundary.rb

@@ -82,7 +82,7 @@ module Hecks
           return not_applicable("#{bluebook.name} is bound to #{adapter_name}, not PostgresEra")
         end
 
-        settings = registry.world(bluebook.name)&.for_binding(Hecks::Ports::Persistence::VERB, adapter_name) || {}
+        settings = registry.binding_settings(bluebook.name, Hecks::Ports::Persistence::VERB, adapter_name)
         db = Hecks::Adapters::PostgresEra.connect_for(bluebook.name, settings)
         begin
           lineage = Hecks::Adapters::PostgresEra::Lineage.new(db, bluebook.name)

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -200,8 +200,8 @@ module Hecks
         end
       end
 
-      # Rewrites every `.hecksagon` in the copy to bind through Memory and drops its
-      # `.world` files, so the boot needs no settings at all.
+      # Rewrites every `.hecksagon` in the copy to bind through Memory and replaces its
+      # `.world` files with a `default_adapter "Memory"` one, so the boot needs no settings.
       #
       # @param copy [String] the isolated copy's root directory
       # @return [void]
@@ -219,8 +219,11 @@ module Hecks
         # `data/<table>.db` under `root:` when unset — the same
         # zero-config default Memory gets from having no `.world` at
         # all), so the simplest correct fix for either target is
-        # dropping `.world` from the copy entirely.
-        Dir.glob(File.join(copy, "**", "*.world")).each { |path| File.delete(path) }
+        # dropping the shipped `.world` from the copy. What replaces it is
+        # only a `default_adapter`, so an aggregate the hecksagon leaves
+        # unbound (the real world's `default_adapter` bound it) still lands on
+        # this mode's adapter — see `write_default_worlds!`.
+        write_default_worlds!(copy, "Memory")
       end
 
       # Same dance as memory, one adapter over — `Adapters::Sqlite#
@@ -237,7 +240,7 @@ module Hecks
       def rebind_to_sqlite!(copy)
         rewrite_bindings!(copy, "SqlitePersistence")
         strip_translations!(copy)
-        Dir.glob(File.join(copy, "**", "*.world")).each { |path| File.delete(path) }
+        write_default_worlds!(copy, "SqlitePersistence")
       end
 
       # **The expensive one** — Postgres has no zero-config default the way
@@ -292,6 +295,7 @@ module Hecks
         write_worlds!(copy, "hecks_fuzz_postgres.world") do |name|
           <<~WORLD
             Hecks.world "#{name}" do
+              default_adapter "Postgres"
               persisted_by("Postgres") do
                 database "#{database}"
                 schema "#{schema}"
@@ -299,6 +303,7 @@ module Hecks
             end
           WORLD
         end
+        write_unbound_chapter_worlds!(copy)
       end
 
       # Admin connection lives outside the tmp copy entirely — same as
@@ -442,6 +447,7 @@ module Hecks
         write_worlds!(copy, "hecks_fuzz_postgres_era.world") do |name|
           <<~WORLD
             Hecks.world "#{name}" do
+              default_adapter "PostgresEra"
               persisted_by("PostgresEra") do
                 database "#{database}"
                 schema "#{schema}"
@@ -450,6 +456,54 @@ module Hecks
             end
           WORLD
         end
+        write_unbound_chapter_worlds!(copy)
+      end
+
+      # Replaces every `.world` in the copy with one that declares only `default_adapter`,
+      # so the copy needs no settings and an aggregate its hecksagon leaves unbound
+      # (a chapter whose real world bound it through `default_adapter`) persists through
+      # `adapter_name` like every bound one.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @param adapter_name [String] the persistence adapter every unbound aggregate falls
+      #   back to, such as `"Memory"` or `"SqlitePersistence"`
+      # @return [void]
+      def write_default_worlds!(copy, adapter_name)
+        write_worlds!(copy, "hecks_fuzz_default.world") do |name|
+          <<~WORLD
+            Hecks.world "#{name}" do
+              default_adapter "#{adapter_name}"
+            end
+          WORLD
+        end
+      end
+
+      # Gives every chapter no hecksagon names a world of its own that falls back to Memory.
+      #
+      # A chapter with a bluebook and no hecksagon block (the framework's Privacy) has no
+      # bind, and the worlds `write_worlds!` wrote declare a `default_adapter` that needs a
+      # `database`: left alone, the chapter resolves that adapter through the project's
+      # world with no connection and the boot refuses (`WiringError ... needs a database
+      # connection`). It persisted through Memory before those worlds carried a
+      # `default_adapter`, and a chapter's own world's default wins over the project's, so
+      # this keeps it there.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @return [void]
+      def write_unbound_chapter_worlds!(copy)
+        named = Dir.glob(File.join(copy, "**", "*.hecksagon")).flat_map do |path|
+          File.read(path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten
+        end
+        bluebooks = Dir.glob(File.join(copy, "**", "*.bluebook")).group_by { |path| File.dirname(path) }
+        bluebooks.each do |dir, files|
+          unbound = files.flat_map { |path| File.read(path).scan(/Hecks\.bluebook[\s(]+"([^"]+)"/).flatten }
+                         .uniq - named
+          named.concat(unbound)
+          next if unbound.empty?
+
+          worlds = unbound.map { |name| %(Hecks.world "#{name}" do\n  default_adapter "Memory"\nend\n) }
+          File.write(File.join(dir, "hecks_fuzz_unbound.world"), worlds.join("\n"))
+        end
       end
 
       # Writes one `.world` file per directory that holds a `.hecksagon`, naming every

data/lib/hecks/language/world/world.bluebook

@@ -4,8 +4,10 @@ Hecks.bluebook "World" do
 
     identified_by WorldName, as: :domain
 
-    attribute :realm,  Realm
-    attribute :latest, Latest
+    attribute :realm,            Realm
+    attribute :latest,           Latest
+    attribute :default_database, DefaultDatabase
+    attribute :default_adapter,  DefaultAdapter
 
     value_object "WorldName" do
       attribute :value, String
@@ -22,6 +24,22 @@ Hecks.bluebook "World" do
       invariant("a latest version says something") { !value.to_s.empty? }
     end
 
+    # The connection every chapter's database-taking persistence adapter
+    # uses unless that chapter's own world says otherwise — a world's
+    # per-chapter `persisted_by ... database` block, written once.
+    value_object "DefaultDatabase" do
+      attribute :value, String
+      invariant("a default database says something") { !value.to_s.empty? }
+    end
+
+    # The persistence adapter every aggregate binds to unless its own
+    # chapter's hecksagon binds it — between an explicit bind and the
+    # framework's in-memory fallback.
+    value_object "DefaultAdapter" do
+      attribute :value, String
+      invariant("a default adapter names an adapter") { !value.to_s.empty? }
+    end
+
     command "Declare" do
       role "Deployment"
       goal "Open a world for a domain"
@@ -29,10 +47,14 @@ Hecks.bluebook "World" do
       attribute :domain, WorldName
       attribute :realm,  Realm, optional: true
       attribute :latest, Latest, optional: true
+      attribute :default_database, DefaultDatabase, optional: true
+      attribute :default_adapter,  DefaultAdapter,  optional: true
 
       sets :domain
       sets :realm
       sets :latest
+      sets :default_database
+      sets :default_adapter
 
       emits "WorldDeclared"
     end
@@ -55,6 +77,12 @@ Hecks.bluebook "World" do
       member word: "world",           context: "File",     body: "keywords", inner: "World",          opens: "World",          fills: ""
       member word: "realm",           context: "World",     body: "none", inner: "", opens: "", fills: "realm", calls: "realm_impl"
       member word: "latest",          context: "World",     body: "none", inner: "", opens: "", fills: "latest", calls: "latest_impl"
+      # THE TWO CROSS-CHAPTER DEFAULTS — the same connection string and the
+      # same persistence adapter every chapter of a project repeats, written
+      # once. A chapter's own world (`persisted_by ... database`) and its own
+      # hecksagon bind still win; see docs/implemented/reference/world.md.
+      member word: "default_database", context: "World", body: "none", inner: "", opens: "", fills: "default_database", calls: "default_database_impl"
+      member word: "default_adapter",  context: "World", body: "none", inner: "", opens: "", fills: "default_adapter", calls: "default_adapter_impl"
 
     end
 
@@ -78,6 +106,8 @@ Hecks.bluebook "World" do
       member keyword: "world",           context: "File", at: "1", named: "", kind: "text", required: "true", fills: "domain"
       member keyword: "realm",           context: "World", at: "1", named: "", kind: "text", required: "true", fills: "realm"
       member keyword: "latest",          context: "World", at: "1", named: "", kind: "text", required: "true", fills: "latest"
+      member keyword: "default_database", context: "World", at: "1", named: "", kind: "text", required: "true", fills: "default_database"
+      member keyword: "default_adapter",  context: "World", at: "1", named: "", kind: "text", required: "true", fills: "default_adapter"
 
     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