hecks 3.4.2 → 3.6.0

data/lib/hecks/persistence_legacy_fixture/postgres_stores.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Hecks
+  module PersistenceLegacyFixture
+    class Regenerate
+      # Writing the Postgres and PostgresEra fixtures through scratch databases, which are made
+      # for the run and dropped after it. Included in `Regenerate`.
+      module 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
+
+        private
+
+        def with_scratch_databases
+          admin = PG.connect(dbname: "postgres")
+          admin.exec("SET client_min_messages = warning")
+          SCRATCH.each_value { |name| recreate_database(admin, name) }
+          yield
+        ensure
+          SCRATCH.each_value { |name| admin&.exec("DROP DATABASE IF EXISTS #{name} WITH (FORCE)") }
+          admin&.close
+        end
+
+        def recreate_database(admin, name)
+          admin.exec("DROP DATABASE IF EXISTS #{name} WITH (FORCE)")
+          admin.exec("CREATE DATABASE #{name}")
+        end
+
+        def write_postgres(instances)
+          reset_dir("postgres")
+          write_json("postgres/rows.json", instances.to_h { |instance| postgres_rows(instance) })
+        end
+
+        def postgres_rows(instance)
+          adapter = Hecks::Adapters::Postgres.new(aggregate: instance.aggregate, settings: { database: SCRATCH[:postgres] })
+          adapter.save(instance)
+          name = instance.aggregate.storage_name
+          [name, stored_rows(adapter.instance_variable_get(:@db), name)]
+        end
+
+        def stored_rows(db, name)
+          table = PG::Connection.quote_ident(name)
+          entries = PG::Connection.quote_ident("#{name}_entries")
+          {
+            "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
+          }
+        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)
+          snapshot = adapter.send(:quoted_head_snapshot)
+          {
+            "journal"       => journal_rows(db, adapter.instance_variable_get(:@lineage).quoted_journal,
+                                            instance.aggregate.storage_name),
+            "head_snapshot" => db.exec("SELECT id, ordinal, operation, state FROM #{snapshot} ORDER BY id").to_a
+          }
+        end
+
+        def journal_rows(db, journal, name)
+          db.exec_params(
+            "SELECT ordinal, era, aggregate, aggregate_id, operation, state, mirrors FROM #{journal} " \
+            "WHERE aggregate = $1 ORDER BY ordinal", [name]
+          ).to_a
+        end
+      end
+    end
+  end
+end

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)