hecks 3.5.0 → 3.7.0

data/lib/hecks/persistence_legacy_fixture/regenerate.rb

@@ -4,6 +4,7 @@ require "fileutils"
 require "json"
 require "open3"
 require "tmpdir"
+require_relative "postgres_stores"
 
 module Hecks
   module PersistenceLegacyFixture
@@ -15,11 +16,10 @@ module Hecks
     # this is run, and it is not re-run once adapters write through the state codec: it would
     # overwrite the baseline.
     class Regenerate
+      include PostgresStores
+
       # The scratch database each Postgres-backed store is written to.
-      SCRATCH = {
-        postgres:     "hecks_persistence_legacy_postgres",
-        postgres_era: "hecks_persistence_legacy_postgres_era"
-      }.freeze
+      SCRATCH = PostgresStores::SCRATCH
 
       # Raised when a fixture cannot be written.
       class Failure < StandardError; end
@@ -43,9 +43,7 @@ module Hecks
         require "hecks/ports/persistence/plugins/era"
         require "pg"
         instances = PersistenceLegacyFixture.instances
-        write_heki(instances)
-        write_sqlite(instances)
-        write_d1(instances)
+        write_file_stores(instances)
         with_scratch_databases do
           write_postgres(instances)
           write_postgres_era(instances)
@@ -55,6 +53,12 @@ module Hecks
 
       private
 
+      def write_file_stores(instances)
+        write_heki(instances)
+        write_sqlite(instances)
+        write_d1(instances)
+      end
+
       def reset_dir(name)
         dir = File.join(@dir, name)
         FileUtils.rm_rf(dir)
@@ -66,19 +70,6 @@ module Hecks
         File.write(File.join(@dir, relative), "#{JSON.pretty_generate(value)}\n")
       end
 
-      def with_scratch_databases
-        admin = PG.connect(dbname: "postgres")
-        admin.exec("SET client_min_messages = warning")
-        SCRATCH.each_value do |name|
-          admin.exec("DROP DATABASE IF EXISTS #{name} WITH (FORCE)")
-          admin.exec("CREATE DATABASE #{name}")
-        end
-        yield
-      ensure
-        SCRATCH.each_value { |name| admin&.exec("DROP DATABASE IF EXISTS #{name} WITH (FORCE)") }
-        admin&.close
-      end
-
       def write_heki(instances)
         out = reset_dir("heki")
         Dir.mktmpdir("hecks-legacy-heki-") do |tmp|
@@ -98,63 +89,32 @@ module Hecks
             Hecks::Adapters::Sqlite.new(aggregate: instance.aggregate, settings: { database: "banking.sqlite3" },
                                         root: tmp).save(instance)
           end
-          dump, status = Open3.capture2("sqlite3", File.join(tmp, "banking.sqlite3"), ".dump")
-          raise Failure, "sqlite3 .dump failed" unless status.success?
-
-          File.write(File.join(out, "banking.sql"), dump)
+          File.write(File.join(out, "banking.sql"), sqlite_dump(File.join(tmp, "banking.sqlite3")))
         end
       end
 
+      def sqlite_dump(database)
+        dump, status = Open3.capture2("sqlite3", database, ".dump")
+        raise Failure, "sqlite3 .dump failed" unless status.success?
+
+        dump
+      end
+
       def write_d1(instances)
         reset_dir("d1")
         connection = PersistenceLegacyFixture.fake_d1_connection
-        tables = instances.flat_map do |instance|
-          PersistenceLegacyFixture.with_d1_connection(connection) do
-            Hecks::Adapters::D1.new(aggregate: instance.aggregate,
-                                    settings:  { account_id: "acc", database_id: "db", api_token: "tok" }).save(instance)
-          end
-          [instance.aggregate.storage_name, "#{instance.aggregate.storage_name}_entries"]
-        end
+        tables = instances.flat_map { |instance| save_to_d1(instance, connection) }
         write_json("d1/rows.json",
                    tables.to_h { |table| [table, connection.execute(%(SELECT * FROM "#{table}" ORDER BY rowid))] })
       end
 
-      def write_postgres(instances)
-        reset_dir("postgres")
-        rows = instances.to_h do |instance|
-          adapter = Hecks::Adapters::Postgres.new(aggregate: instance.aggregate, settings: { database: SCRATCH[:postgres] })
-          adapter.save(instance)
-          db = adapter.instance_variable_get(:@db)
-          table = PG::Connection.quote_ident(instance.aggregate.storage_name)
-          entries = PG::Connection.quote_ident("#{instance.aggregate.storage_name}_entries")
-          [instance.aggregate.storage_name, {
-            "head"    => db.exec("SELECT * FROM #{table} ORDER BY id").to_a,
-            "entries" => db.exec("SELECT aggregate_id, operation, state, mirrors FROM #{entries} ORDER BY sequence").to_a
-          }]
+      # @return [Array<String>] the tables the instance's aggregate is stored in
+      def save_to_d1(instance, connection)
+        PersistenceLegacyFixture.with_d1_connection(connection) do
+          Hecks::Adapters::D1.new(aggregate: instance.aggregate,
+                                  settings:  { account_id: "acc", database_id: "db", api_token: "tok" }).save(instance)
         end
-        write_json("postgres/rows.json", rows)
-      end
-
-      def write_postgres_era(instances)
-        reset_dir("postgres_era")
-        rows = instances.to_h { |instance| [instance.aggregate.storage_name, era_rows(instance)] }
-        write_json("postgres_era/rows.json", rows)
-      end
-
-      def era_rows(instance)
-        adapter = Hecks::Adapters::PostgresEra.new(aggregate: instance.aggregate,
-                                                   settings:  { database: SCRATCH[:postgres_era] })
-        adapter.save(instance)
-        db = adapter.instance_variable_get(:@db)
-        journal = adapter.instance_variable_get(:@lineage).quoted_journal
-        snapshot = adapter.send(:quoted_head_snapshot)
-        {
-          "journal"       => db.exec_params(
-            "SELECT ordinal, era, aggregate, aggregate_id, operation, state, mirrors FROM #{journal} " \
-            "WHERE aggregate = $1 ORDER BY ordinal", [instance.aggregate.storage_name]
-          ).to_a,
-          "head_snapshot" => db.exec("SELECT id, ordinal, operation, state FROM #{snapshot} ORDER BY id").to_a
-        }
+        [instance.aggregate.storage_name, "#{instance.aggregate.storage_name}_entries"]
       end
     end
   end

data/lib/hecks/persistence_legacy_fixture.rb

@@ -53,17 +53,20 @@ module Hecks
 
     # @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")
+      @bluebook ||= load_banking.bluebook("Banking")
+    end
+
+    # @return [Hecks::Runtime::Registry] a registry holding the banking example's bluebooks
+    def load_banking
+      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
     end
 
     # @param name [String] an aggregate of banking

data/lib/hecks/ports/access_control.rb

@@ -80,17 +80,20 @@ module Hecks
       #   or the one that does has no Ruby implementation under `Hecks::Adapters`
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can answer who's allowed in"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can answer who's allowed in" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/agent/answers.rb

@@ -123,7 +123,7 @@ module Hecks
           kind = row["kind"].to_s.to_sym
           return kind if CRITIQUE_KINDS.include?(kind)
 
-          raise ValidationError, "#{kind.inspect} is not a critique kind this port knows (#{CRITIQUE_KINDS.join(', ')})"
+          raise ValidationError, "#{kind.inspect} is not a critique kind this port knows (#{CRITIQUE_KINDS.join(", ")})"
         end
 
         # Reads a finding row's severity, refusing anything but the two that exist.
@@ -136,7 +136,7 @@ module Hecks
           severity = row["severity"].to_s.to_sym
           return severity if SEVERITIES.include?(severity)
 
-          raise ValidationError, "#{severity.inspect} is not a severity this port knows (#{SEVERITIES.join(', ')})"
+          raise ValidationError, "#{severity.inspect} is not a severity this port knows (#{SEVERITIES.join(", ")})"
         end
 
         # Normalises a proposal row's arguments into symbol-keyed, all-String rows.

data/lib/hecks/ports/agent.rb

@@ -109,17 +109,20 @@ module Hecks
       #   one that does has no Ruby implementation under `Hecks::Adapters`
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can conduct an interview"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can conduct an interview" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/authentication.rb

@@ -47,17 +47,20 @@ module Hecks
       # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can authenticate a sign-in"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can authenticate a sign-in" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/authorization.rb

@@ -57,17 +57,20 @@ module Hecks
       # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can answer a role check"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can answer a role check" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/clock.rb

@@ -26,17 +26,20 @@ module Hecks
       # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can say what time it is"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can say what time it is" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/extraction.rb

@@ -33,19 +33,20 @@ module Hecks
         end
 
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can recover a " \
-                "predicate's source"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime " \
-                "will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can recover a predicate's source" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/identity_assignment.rb

@@ -28,17 +28,20 @@ module Hecks
       # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can assign an identity"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can assign an identity" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/identity_generation.rb

@@ -23,17 +23,20 @@ module Hecks
       # @raise [Runtime::WiringError] if none, or more than one, implements this port
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can mint an identity"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can mint an identity" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/identity_resolution.rb

@@ -31,17 +31,20 @@ module Hecks
       #   or the one that does has no Ruby implementation under `Hecks::Adapters`
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can resolve an identity"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can resolve an identity" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

data/lib/hecks/ports/key_vault.rb

@@ -32,17 +32,20 @@ module Hecks
       # Refuses an ambiguous wiring rather than choosing an adapter arbitrarily.
       def adapter(registry)
         implementations = registry.adapters.values.select { |a| a.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
 
-        case implementations.size
-        when 1 then registry.adapter_class(implementations.first.name)
-        when 0
-          raise Runtime::WiringError,
-                "no adapter implements the #{NAME} port — nothing can issue or destroy a key"
-        else
-          raise Runtime::WiringError,
-                "#{implementations.size} adapters implement the #{NAME} port " \
-                "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
-        end
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # Words the refusal for a port that resolves to no adapter or to several.
+      #
+      # @param implementations [Array] the adapters bound to this port
+      # @return [String] the error message
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can issue or destroy a key" if implementations.empty?
+
+        names = implementations.map(&:name).sort.join(", ")
+        "#{implementations.size} adapters implement the #{NAME} port (#{names}) — the runtime will not choose for you"
       end
     end
   end

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

@@ -40,10 +40,10 @@ module Hecks
           @adapter = adapter
           required = %i[append project entries]
           missing = required.reject { |method| adapter.respond_to?(method) }
-          unless missing.empty?
-            raise Runtime::WiringError,
-                  "#{adapter.class} does not implement append-only persistence: #{missing.join(', ')}"
-          end
+          return if missing.empty?
+
+          raise Runtime::WiringError,
+                "#{adapter.class} does not implement append-only persistence: #{missing.join(", ")}"
         end
 
         # Reads one record's current projected state from the adapter.
@@ -228,7 +228,7 @@ module Hecks
         # @return [Boolean] true when a record was found and deleted, false when there was
         #   none and nothing was journaled
         # @raise [Runtime::WiringError] when the adapter's `append` or `project` refuses
-        def delete(id)
+        def delete(id) # rubocop:disable Naming/PredicateMethod -- the repository port's verb, answering whether a record existed
           return false unless find(id)
 
           entry = Entry.new(operation: "delete", id: id.to_s, state: nil)

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

@@ -1,4 +1,4 @@
-require_relative "../../bluebook/hexagon"
+require_relative "../../bluebook/hecksagon"
 require_relative "../../runtime/registry"
 
 module Hecks
@@ -20,21 +20,45 @@ 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)
-          declared = registry.default_adapter_for(domain)
-          return default_binding(aggregate, declared || DEFAULT_ADAPTER) unless hexagon
+          hecksagon = registry.hecksagon(domain)
+          declared  = registry.default_adapter_for(domain)
+          return default_binding(aggregate, declared || DEFAULT_ADAPTER) unless hecksagon
 
-          bindings = hexagon.binds_for(aggregate.hecks_name, VERB)
-          bindings = [default_binding(aggregate, declared)] if bindings.empty? && declared
+          bindings = declared_bindings(hecksagon, aggregate, declared)
           raise missing_binding(domain, aggregate) if bindings.empty?
 
+          authoritative_among(bindings, domain, aggregate)
+        end
+
+        # Picks the single roleless bind, refusing any other count and any bind with a role.
+        #
+        # @param bindings [Array<Bluebook::Bind>] the aggregate's binds; not empty
+        # @param domain [String, Symbol] name of the domain, used in refusal messages
+        # @param aggregate [Bluebook::Aggregate] the aggregate the binds belong to
+        # @return [Bluebook::Bind] the authoritative bind
+        # @raise [Runtime::WiringError] if the roleless count is not one, or a role is present
+        def authoritative_among(bindings, domain, aggregate)
           authoritative = bindings.select { |bind| bind.role.nil? || bind.role.empty? }
           raise ambiguous_binding(domain, aggregate, authoritative) unless authoritative.size == 1
-          raise unsupported_roles(domain, aggregate, bindings - authoritative) unless (bindings - authoritative).empty?
+
+          roled = bindings - authoritative
+          raise unsupported_roles(domain, aggregate, roled) unless roled.empty?
 
           authoritative.first
         end
 
+        # Lists the hecksagon's `persisted_by` binds for an aggregate, or the world's default
+        # adapter bind when the hecksagon declares none.
+        #
+        # @param hecksagon [Bluebook::Hexagon] the domain's hecksagon
+        # @param aggregate [Bluebook::Aggregate] the aggregate whose binds are wanted
+        # @param declared [String, nil] the world's default adapter, if any
+        # @return [Array<Bluebook::Bind>] the binds; empty when none and no default exists
+        def declared_bindings(hecksagon, aggregate, declared)
+          bindings = hecksagon.binds_for(aggregate.hecks_name, VERB)
+          bindings.empty? && declared ? [default_binding(aggregate, declared)] : bindings
+        end
+
         # Builds the bind an aggregate gets when its domain declares no hecksagon.
         #
         # @param aggregate [Bluebook::Aggregate] the aggregate to bind
@@ -81,8 +105,8 @@ module Hecks
         # @return [Runtime::WiringError] an error whose message lists each role
         def unsupported_roles(domain, aggregate, bindings)
           Runtime::WiringError.new(
-            "#{domain}::#{aggregate.hecks_name} uses persistence role#{'s' unless bindings.size == 1} " \
-            "#{bindings.map(&:role).map(&:inspect).join(', ')}. Only persisted_by is supported."
+            "#{domain}::#{aggregate.hecks_name} uses persistence role#{"s" unless bindings.size == 1} " \
+            "#{bindings.map { |binding| binding.role.inspect }.join(", ")}. Only persisted_by is supported."
           )
         end
       end