hecks 3.5.0 → 3.6.0

data/lib/hecks/language/bluebook/vocabulary.bluebook

@@ -622,7 +622,7 @@ Hecks.bluebook "Bluebook" do
       attribute :label,    String
 
       member name: "runtime_changed", workflow: "ci.yml", mode: "touches",
-             pattern: '^lib/hecks/runtime/', push: "skip",
+             pattern: '^lib/hecks/runtime/', push: "before_sha",
              label: "does this change touch lib/hecks/runtime/**?"
       member name: "postgres_io_relevant_changed", workflow: "ci-postgres-io-parallel.yml", mode: "skips_unless",
              pattern: '^(docs/|editors/|release/|deploy/|\.claude/|\.githooks/|rust/(parser|codegen|host|build|lsp|web|tests)/|\.rubocop\.yml$|\.rubocop_todo\.yml$|\.mcp\.json$|\.rspec-local\.example$|README\.md$|CHANGELOG\.md$|CONTRIBUTING\.md$|SECURITY\.md$|LICENSE$|\.gitignore$)',
@@ -630,6 +630,48 @@ Hecks.bluebook "Bluebook" do
              label: "does this change touch anything rspec_postgres_io_parallel covers?"
     end
 
+    # The checks a commit must have passed before a `Promotion` moves it onto a guarded lane. Each
+    # is the name of a job in .github/workflows that reports to a commit as a check run; a check
+    # that a path gate skipped reports `skipped`, which counts as passed. `hecks promote` reads
+    # these rows, and hecks project_lanes writes them into the ruleset of any lane that requires
+    # them, so the list lives here and nowhere else.
+    value_object "RequiredCheck" do
+      attribute :name, String
+
+      member name: "rspec"
+      member name: "checks"
+      member name: "rspec_postgres_io"
+      member name: "rspec_postgres_io_parallel"
+      member name: "rspec_rust_io"
+      member name: "rspec_rust_parser"
+      member name: "rspec_rust_codegen"
+      member name: "rspec_rust_host"
+      member name: "rspec_fuzzing"
+    end
+
+    # The branches a change travels along. `main` takes pushes with no gate; `stable` takes only
+    # what a `Promotion` moves onto it once every `CiGate` check is green on that commit.
+    # hecks project_lanes writes each row's ruleset into .github/rulesets/<name>.json, and
+    # `hecks promote` reads `follows` to know which lane a promotion fast-forwards.
+    #
+    # `guarded` says whether a ruleset restricts the branch. `pushers` says what it takes: `anyone`
+    # (any commit), or `green` (only a commit on which every `RequiredCheck` has already passed,
+    # which is how a promotion moves the lane). `feeds` is the tag that moves with the lane, or
+    # empty when none does; `follows` is the lane a promotion draws from, or empty. `alert_after`
+    # is the whole hours the lane may stand behind the lane it follows before `hecks
+    # promotion_run.watch` files a finding, or empty for a lane that is never late.
+    value_object "Lane" do
+      attribute :name,        String
+      attribute :guarded,     String
+      attribute :pushers,     String
+      attribute :feeds,       String
+      attribute :follows,     String
+      attribute :alert_after, String
+
+      member name: "main",   guarded: "no",  pushers: "anyone", feeds: "",     follows: "",     alert_after: ""
+      member name: "stable", guarded: "yes", pushers: "green",  feeds: "edge", follows: "main", alert_after: "4"
+    end
+
     # The dials of the hecks_qa loop: what each is called, the type of value it takes and what it
     # does. qa/settings.yml holds the values, which are edited and reviewed as a diff; this table
     # holds the rest, so the loader (`Hecks::Fuzzing::QaSettings`) checks the file against it and

data/lib/hecks/literal/item_splitter.rb

@@ -0,0 +1,50 @@
+module Hecks
+  module Literal
+    # Splits the text between a literal's outer braces or brackets on separator commas only:
+    # never one inside a quoted string or a nested brace or bracket.
+    class ItemSplitter
+      # @param body [String] the text between a literal's outer braces or brackets
+      def initialize(body)
+        @body = body
+        @items = []
+        @current = +""
+        @depth = 0
+        @quoting = false
+        @escaping = false
+      end
+
+      # @return [Array<String>] each item's raw text, stripped, with empty items dropped
+      def call
+        @body.each_char do |char|
+          @current << char
+          consume(char)
+        end
+        @items << @current
+        @items.map(&:strip).reject(&:empty?)
+      end
+
+      private
+
+      def consume(char)
+        return @escaping = false if @escaping
+        return @escaping = true if @quoting && char == "\\"
+        return @quoting = !@quoting if char == '"'
+
+        track_nesting(char) unless @quoting
+      end
+
+      # Follows brace and bracket depth, and separates at a comma outside any.
+      def track_nesting(char)
+        @depth += 1 if "{[".include?(char)
+        @depth -= 1 if "}]".include?(char)
+        separate if char == "," && @depth.zero?
+      end
+
+      def separate
+        @current.chop!
+        @items << @current
+        @current = +""
+      end
+    end
+  end
+end

data/lib/hecks/literal.rb

@@ -1,3 +1,5 @@
+require_relative "literal/item_splitter"
+
 module Hecks
   # A mutation source that reads the record's own state: `append: { knights: state(:knights) }`.
   # A bare Symbol in a mutation source names a command argument, so this is the only way to say it.
@@ -23,38 +25,51 @@ module Hecks
       when Symbol then ":#{value}"
       when String then quote(value)
       when StateRef, true, false, Integer, Float then value.to_s
-      when Hash   then "{#{value.map { |key, held| "#{key}: #{render(held)}" }.join(', ')}}"
-      when Array  then "[#{value.map { |held| render(held) }.join(', ')}]"
+      when Hash, Array then render_collection(value)
       else
         raise ArgumentError, "#{value.class} has no pinned literal spelling — teach Literal.render one " \
                              "rather than letting #to_s decide it"
       end
     end
 
+    # @param value [Hash, Array] a collection to render
+    # @return [String] `{key: value}` for a Hash, `[value, ...]` for an Array, each element rendered
+    def render_collection(value)
+      return "[#{value.map { |held| render(held) }.join(", ")}]" if value.is_a?(Array)
+
+      "{#{value.map { |key, held| "#{key}: #{render(held)}" }.join(", ")}}"
+    end
+
     # Parses a wire spelling back into a Ruby value; the exact inverse of `render`.
     # A bare word stays a String, since some fields are stored as plain text, never rendered.
     #
     # @param text [String, #to_s] wire spelling produced by `render`, or a bare word
     # @return [Object] nil, true, false, Integer, Float, Symbol, StateRef, String,
     #   Hash, or Array — or `text` itself, stripped, when it matches no known spelling
-    # rubocop:disable-next Metrics/CyclomaticComplexity
-    # rubocop:disable-next Metrics/PerceivedComplexity
     def read(text)
       raw = text.to_s.strip
       return nil if raw.empty? || raw == "nil"
-      return true if raw == "true"
-      return false if raw == "false"
-      return raw.to_i if raw.match?(/\A-?\d+\z/)
-      return raw.to_f if raw.match?(/\A-?\d+\.\d+\z/)
-      return raw[1..].to_sym if raw.start_with?(":")
-      return StateRef.new(raw[7..-2].to_sym) if raw.match?(/\Astate\(:[A-Za-z_][A-Za-z0-9_]*\)\z/)
-      return unquote(raw) if quoted?(raw)
-      return read_hash(raw) if raw.start_with?("{") && raw.end_with?("}")
-      return read_array(raw) if raw.start_with?("[") && raw.end_with?("]")
+      return KEYWORD_VALUES[raw] if KEYWORD_VALUES.key?(raw)
 
+      READERS.each { |matches, convert| return convert.call(raw) if matches.call(raw) }
       raw
     end
 
+    # The words that read as `true` and `false`.
+    KEYWORD_VALUES = { "true" => true, "false" => false }.freeze
+
+    # Each spelling `read` recognizes after the keywords, in the order it tries them: whether the
+    # text is that spelling, and how to turn it into its value.
+    READERS = [
+      [->(raw) { raw.match?(/\A-?\d+\z/) }, :to_i.to_proc],
+      [->(raw) { raw.match?(/\A-?\d+\.\d+\z/) }, :to_f.to_proc],
+      [->(raw) { raw.start_with?(":") }, ->(raw) { raw[1..].to_sym }],
+      [->(raw) { raw.match?(/\Astate\(:[A-Za-z_][A-Za-z0-9_]*\)\z/) }, ->(raw) { StateRef.new(raw[7..-2].to_sym) }],
+      [->(raw) { quoted?(raw) }, ->(raw) { unquote(raw) }],
+      [->(raw) { raw.start_with?("{") && raw.end_with?("}") }, ->(raw) { read_hash(raw) }],
+      [->(raw) { raw.start_with?("[") && raw.end_with?("]") }, ->(raw) { read_array(raw) }]
+    ].freeze
+
     ESCAPED = { '"' => '\\"', "\\" => "\\\\" }.freeze
 
     # Wraps `text` in double quotes, escaping embedded quotes and backslashes.
@@ -96,30 +111,6 @@ module Hecks
     #
     # @param body [String] the text between a literal's outer braces or brackets
     # @return [Array<String>] each item's raw text, stripped, with empty items dropped
-    def split_items(body)
-      items = []
-      current = +""
-      depth = 0
-      quoting = false
-      escaping = false
-
-      body.each_char do |char|
-        current << char
-        next (escaping = false) if escaping
-        next (escaping = true) if quoting && char == "\\"
-        next (quoting = !quoting) if char == '"'
-        next if quoting
-
-        depth += 1 if "{[".include?(char)
-        depth -= 1 if "}]".include?(char)
-        next unless char == "," && depth.zero?
-
-        current.chop!
-        items << current
-        current = +""
-      end
-      items << current
-      items.map(&:strip).reject(&:empty?)
-    end
+    def split_items(body) = ItemSplitter.new(body).call
   end
 end

data/lib/hecks/mcp_stdio_guard.rb

@@ -42,15 +42,15 @@ module Hecks
     # carries the MCP protocol, and a 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
+    # @param checks [Hash{Symbol => Object}] what `violations` looks at: `argv:` (the command-line
+    #   arguments), `env:` (the process environment), `stdin:` (the stream requests arrive on) and
+    #   `stdout:` (the stream responses leave on)
     # @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)
+    # @raise [ArgumentError] for any other keyword
+    def enforce_stdio!(server:, stderr: $stderr, **checks)
+      found = violations(**checks)
       refuse!(server, found, stderr) unless found.empty?
     end
 
@@ -88,7 +88,7 @@ module Hecks
     # @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"
+        "argument #{arg.inspect} is not accepted (only #{ACCEPTED_ARGS.join(", ")}); network options are refused, not ignored"
       end
     end
 
@@ -96,7 +96,7 @@ module Hecks
     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(', ')}"
+          "except #{ACCEPTED_ENV.map { |k, v| "#{k}=#{v}" }.join(", ")}"
       end
     end
 

data/lib/hecks/naming.rb

@@ -74,7 +74,7 @@ module Hecks
       when 0 then ""
       when 1 then items[0].to_s
       when 2 then "#{items[0]} #{conj} #{items[1]}"
-      else "#{items[0..-2].join(', ')}, #{conj} #{items[-1]}"
+      else "#{items[0..-2].join(", ")}, #{conj} #{items[-1]}"
       end
     end
 
@@ -112,13 +112,19 @@ module Hecks
 
       # Undo `plural`'s "es" after s/x/z/ch/sh before the bare-"s" rule, so "Boxes"
       # gives "Box" while "Invoices" still gives "Invoice".
-      return word[0..-3] if word.length > 3 && word.end_with?("es") && word[0..-3].match?(/(s|x|z|ch|sh)\z/)
+      return word[0..-3] if sibilant_es?(word)
 
       return word[0..-2] if word.length > 1 && word.end_with?("s")
 
       word
     end
 
+    # @param word [String] a plural name
+    # @return [Boolean] whether it is a sibilant stem plus `plural`'s "es"
+    def sibilant_es?(word)
+      word.length > 3 && word.end_with?("es") && word[0..-3].match?(/(s|x|z|ch|sh)\z/)
+    end
+
     # Derives the attribute name a reference to `type` is stored under.
     #
     # @param type [Module, String, Symbol, #to_s] the referenced construct's name
@@ -175,7 +181,7 @@ module Hecks
       domain, aggregate, *rest = path.to_s.split("::")
       return nil unless domain && aggregate
 
-      command = "#{rest.join('.')}.#{command}" unless rest.empty?
+      command = "#{rest.join(".")}.#{command}" unless rest.empty?
 
       [domain, aggregate, command]
     end

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