hecks 3.14.0 → 4.0.0

data/lib/hecks/bluebook/translation_expression/evaluator.rb

@@ -0,0 +1,63 @@
+module Hecks
+  module Bluebook
+    module TranslationExpression
+      # Computes a parsed expression for one record's state. The reference semantics the
+      # compiled Postgres form is held to.
+      module Evaluator
+        module_function
+
+        # @param tree [Array] a tree `TranslationExpression.parse` returned
+        # @param state [Hash] the record's stored state
+        # @return [String, nil] the computed text; nil when the expression has no value
+        def call(tree, state)
+          case tree.first
+          when "lit" then tree[1]
+          when "null" then nil
+          when "ref" then reference(tree[1], state)
+          else apply(tree.first, tree.drop(1), state)
+          end
+        end
+
+        # Reads a dotted path out of a record; only text counts as a value.
+        def reference(path, state)
+          value = path.split(".").inject(state) { |held, key| held.is_a?(Hash) ? member(held, key) : nil }
+          value.is_a?(String) ? value : nil
+        end
+
+        # A record's top-level keys are symbols, a value object's are strings.
+        def member(hash, key) = hash.key?(key.to_sym) ? hash[key.to_sym] : hash[key]
+
+        def apply(name, arguments, state)
+          return lookup(arguments, state) if name == "lookup"
+          return replace(arguments, state) if name == "replace"
+
+          values = arguments.map { |argument| call(argument, state) }
+          return nil if values.any?(&:nil?)
+
+          fold(name, values)
+        end
+
+        def fold(name, values)
+          case name
+          when "lower" then values.first.downcase(:ascii)
+          when "upper" then values.first.upcase(:ascii)
+          else values.join
+          end
+        end
+
+        def replace(arguments, state)
+          target, from, to = arguments
+          call(target, state)&.gsub(from.last) { to.last }
+        end
+
+        def lookup(arguments, state)
+          key, table, fallback = arguments
+          value = call(key, state)
+          return nil if value.nil?
+
+          table.fetch(value) { call(fallback, state) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/translation_expression/parser.rb

@@ -0,0 +1,127 @@
+require "json"
+require "strscan"
+
+module Hecks
+  module Bluebook
+    module TranslationExpression
+      # Reads the text of an expression into its tree, refusing anything outside the language.
+      class Parser
+        NAME   = /[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)*/
+        STRING = /"(?:[^"\\]|\\.)*"/
+
+        # @param text [String] the expression's source text
+        def initialize(text)
+          @text = text.to_s
+          @scan = StringScanner.new(@text)
+        end
+
+        # @return [Array] the expression tree
+        # @raise [TranslationExpression::Refused] if the text is not a well-formed expression
+        def call
+          tree = expression
+          skip
+          refuse("unexpected #{@scan.rest[0, 12].inspect} after the expression") unless @scan.eos?
+          tree
+        end
+
+        private
+
+        def expression
+          skip
+          return ["lit", string] if @scan.check(/"/)
+
+          name = @scan.scan(NAME) || refuse("expected a field, a string or a function")
+          return function(name) if @scan.check(/\s*\(/)
+
+          name == "null" ? ["null"] : ["ref", name]
+        end
+
+        def function(name)
+          refuse("#{name} is not a function (#{FUNCTIONS.keys.join(", ")})") unless FUNCTIONS.key?(name)
+          punct("(")
+          arguments = list { argument(name, _1) }
+          punct(")")
+          check_arguments(name, arguments)
+          [name, *arguments]
+        end
+
+        def argument(name, index)
+          skip
+          return table if name == "lookup" && index == 1
+
+          expression
+        end
+
+        def list
+          items = []
+          loop do
+            items << yield(items.size)
+            skip
+            break unless @scan.skip(/,/)
+          end
+          items
+        end
+
+        def table
+          punct("{")
+          pairs = list { pair }
+          punct("}")
+          refuse("a lookup table repeats a key") unless pairs.map(&:first).uniq.size == pairs.size
+          pairs.to_h
+        end
+
+        def pair
+          skip
+          key = string
+          punct(":")
+          skip
+          [key, string]
+        end
+
+        def string
+          token = @scan.scan(STRING) || refuse("expected a string")
+          JSON.parse(token, quirks_mode: true)
+        rescue JSON::ParserError
+          refuse("#{token} is not a well-formed string")
+        end
+
+        def punct(mark)
+          skip
+          @scan.skip(Regexp.new(Regexp.escape(mark))) || refuse("expected #{mark.inspect}")
+        end
+
+        def skip = @scan.skip(/\s+/)
+
+        def check_arguments(name, arguments)
+          arity = FUNCTIONS.fetch(name)
+          refuse("#{name} takes #{arity} expressions, not #{arguments.size}") if arity && arguments.size != arity
+          refuse("concat takes two or more expressions") if arity.nil? && arguments.size < 2
+          check_literals(name, arguments)
+        end
+
+        def check_literals(name, arguments)
+          case name
+          when "replace" then check_replace(arguments)
+          when "lookup" then check_lookup(arguments)
+          end
+        end
+
+        def check_replace(arguments)
+          _target, from, to = arguments
+          refuse("replace needs string literals for what to find and what to put") unless [from, to].all? { _1.first == "lit" }
+          refuse("replace cannot look for an empty string") if from.last.empty?
+        end
+
+        def check_lookup(arguments)
+          _key, table, fallback = arguments
+          refuse("lookup needs a table of at least one pair") unless table.is_a?(Hash) && !table.empty?
+          refuse("lookup needs a string literal or null as its fallback") unless %w[lit null].include?(fallback.first)
+        end
+
+        def refuse(why)
+          raise Refused, "#{why} (in #{@text.inspect} at offset #{@scan.pos})"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/translation_expression.rb

@@ -0,0 +1,39 @@
+require_relative "translation_expression/parser"
+require_relative "translation_expression/evaluator"
+
+module Hecks
+  module Bluebook
+    # The expression a `derive` rule computes a new field from: text functions over the record's
+    # stored text, with no storage engine in sight. It parses to a tree of plain arrays, which
+    # is also its plan form:
+    #
+    #   ["ref", "name.value"]  ["lit", "text"]  ["null"]
+    #   ["lower", x]  ["upper", x]  ["concat", x, y, ...]
+    #   ["replace", x, ["lit", from], ["lit", to]]
+    #   ["lookup", x, {"key" => "value"}, ["lit", default] | ["null"]]
+    #
+    # A reference that is missing or not text has no value, and a function with a valueless
+    # argument has none either.
+    module TranslationExpression
+      # Raised when the text of an expression is not one the language accepts.
+      class Refused < StandardError; end
+
+      # The functions and how many expressions each takes; `nil` means "two or more".
+      FUNCTIONS = { "lower" => 1, "upper" => 1, "concat" => nil, "replace" => 3, "lookup" => 3 }.freeze
+
+      # Parses an expression's text into its tree.
+      #
+      # @param text [String] the expression, e.g. `lower(name.value)`
+      # @return [Array] the expression tree
+      # @raise [Refused] if the text is not a well-formed expression
+      def self.parse(text) = Parser.new(text).call
+
+      # Computes an expression's value for one record's state.
+      #
+      # @param tree [Array] a tree `parse` returned
+      # @param state [Hash] the record's stored state
+      # @return [String, nil] the text it computes; nil when it has no value
+      def self.evaluate(tree, state) = Evaluator.call(tree, state)
+    end
+  end
+end

data/lib/hecks/bluebook/translation_plan.rb

@@ -0,0 +1,70 @@
+module Hecks
+  module Bluebook
+    # A translation as data: each aggregate's rules as an ordered list of ops any runtime can
+    # interpret, with nothing in them that names a storage engine. In the order they apply to a
+    # record, each op has its name under "op" plus:
+    #
+    #   derive "to" "expression" (a tree)   rename "from" "to"   move "from" "to" (dotted paths)
+    #   convert "from" "to" "values" ([old, new] pairs)   drop "path"   retype "from" "to"
+    #   backfill "path" "default"   rekey_to "to"
+    module TranslationPlan
+      VERSION = 1
+
+      # The op names, in the order they apply; one per rule list of a `TranslationAggregate`.
+      OPS = %w[derive rename move convert drop retype backfill rekey_to].freeze
+
+      module_function
+
+      # @param translation [Bluebook::Translation] a declared translation edge
+      # @return [Hash] the edge as plain data, ready for `JSON.generate`
+      def build(translation)
+        {
+          "version" => VERSION, "domain" => translation.domain, "from" => translation.from.to_s,
+          "to" => translation.to.to_s, "retired" => translation.retired.map(&:to_s),
+          "aggregates" => translation.aggregates.map { |aggregate| aggregate_plan(aggregate) }
+        }
+      end
+
+      def aggregate_plan(aggregate)
+        { "name" => aggregate.name, "was" => aggregate.was, "ops" => ops(aggregate) }
+      end
+
+      def ops(aggregate)
+        [*derives(aggregate), *renames(aggregate), *moves(aggregate), *converts(aggregate), *drops(aggregate),
+         *retypes(aggregate), *backfills(aggregate), *rekeys(aggregate)]
+      end
+
+      def derives(aggregate)
+        aggregate.derives.map { |d| { "op" => "derive", "to" => d.to, "expression" => d.tree } }
+      end
+
+      def renames(aggregate)
+        aggregate.renames.map { |from, to| { "op" => "rename", "from" => from.to_s, "to" => to.to_s } }
+      end
+
+      def moves(aggregate)
+        aggregate.moves.map { |m| { "op" => "move", "from" => m.from, "to" => m.to } }
+      end
+
+      def converts(aggregate)
+        aggregate.converts.map do |c|
+          { "op" => "convert", "from" => c.from, "to" => c.to, "values" => c.values.map { |old, new| [old, new] } }
+        end
+      end
+
+      def drops(aggregate) = aggregate.drops.map { |path| { "op" => "drop", "path" => path.to_s } }
+
+      def retypes(aggregate)
+        aggregate.retypes.map { |r| { "op" => "retype", "from" => r.from, "to" => r.to } }
+      end
+
+      def backfills(aggregate)
+        aggregate.backfills.map { |b| { "op" => "backfill", "path" => b.name.to_s, "default" => b.default } }
+      end
+
+      def rekeys(aggregate)
+        aggregate.rekeys.map { |rekey| { "op" => "rekey_to", "to" => rekey.to } }
+      end
+    end
+  end
+end

data/lib/hecks/bluebook.rb

@@ -29,7 +29,9 @@ require_relative "bluebook/ask_resolution"
 require_relative "bluebook/process_manager"
 require_relative "bluebook/aggregate"
 require_relative "bluebook/hecksagon"
+require_relative "bluebook/translation_expression"
 require_relative "bluebook/translation"
+require_relative "bluebook/translation_plan"
 
 require_relative "bluebook/assembly/contract"
 require_relative "bluebook/assembly/contracts"

data/lib/hecks/chapters.rb

@@ -5,8 +5,8 @@ require_relative "bluebook/meta_validator"
 
 module Hecks
   # The chapters the gem carries that a hecksagon can attach by name (ADR 0080): the language
-  # declared in itself, Expression, Tenancy, Deploy, Site, Tickets and QualityControl. Framework
-  # members stay in `Framework`; `table` and `attach!` find a name across both.
+  # declared in itself, Expression, Tenancy, Deploy, Site, Tickets, Composer and QualityControl.
+  # Framework members stay in `Framework`; `table` and `attach!` find a name across both.
   #
   # A chapter is named by the `Hecks.bluebook "Name"` header of its files, and may span several.
   # Beside its bluebook a chapter may carry what every hecksagon attaching it needs, whatever
@@ -16,7 +16,7 @@ module Hecks
     # Where attachable chapters live, relative to `lib/hecks/`.
     GLOBS = %w[language/**/*.bluebook grammar/expression.bluebook tenancy/bluebook/*.bluebook
                deploy/bluebook/*.bluebook site/bluebook/*.bluebook tickets/bluebook/*.bluebook
-               quality_control/*.bluebook].freeze
+               composer/bluebook/*.bluebook quality_control/*.bluebook].freeze
 
     # Every attachable chapter, by name, with the files that declare it.
     #

data/lib/hecks/composer/adapters/claude_composer.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "ClaudeComposer" do
+  port "composer_agent"
+end

data/lib/hecks/composer/adapters/claude_composer.rb

@@ -0,0 +1,83 @@
+require "json"
+require "open3"
+require "timeout"
+
+require_relative "../agent"
+require_relative "jev"
+
+module Hecks
+  module Adapters
+    # Real `composer_agent` fulfillment for `draft` and `wire`: the developer's own `claude` run
+    # as the `hecks-composer` agent, which edits the workspace's files in place. Transport only;
+    # whether the edit is any good is the Composer's own check to judge.
+    #
+    # The agent's write guard confines it to domain files inside the git checkout, so the
+    # workspace must sit inside one.
+    module ClaudeComposer
+      TIMEOUT_SECONDS = 300
+
+      AGENT = "hecks-composer".freeze
+
+      DRAFT = "Edit the domain files in %<dir>s as the request below says. Change only what it asks " \
+              "for, write the bluebook first, then any hecksagon wiring it needs. Reply with one line " \
+              "saying what you changed.".freeze
+
+      WIRE = "Change how the chapter in %<dir>s is wired, as the request below says: edit only its " \
+             ".hecksagon and .world files, and bind adapters that already exist. Reply with one line " \
+             "saying what you changed.".freeze
+
+      module_function
+
+      # @param prompt [String] what the author asked for
+      # @param dir [String] the workspace directory
+      # @return [Hash] `"note"` the agent's account of what it changed
+      # @raise [Ports::Agent::Unavailable] see {Composer::Agent::Unavailable}
+      def draft(prompt:, dir:) = call(DRAFT, prompt, dir)
+
+      # @param prompt [String] what the author asked for
+      # @param dir [String] the workspace directory
+      # @return [Hash] `"note"` the agent's account of what it changed
+      def wire(prompt:, dir:) = call(WIRE, prompt, dir)
+
+      # Naming what a prompt asks for is the `jev` categorizer's work, which this adapter lends.
+      #
+      # @param prompt [String] what the author typed
+      # @return [Hash] `"intent"` one of {Composer::Agent::INTENTS}
+      # @raise [Composer::Agent::Unavailable] if `jev` cannot answer
+      def classify(prompt:) = Jev.classify(prompt: prompt)
+
+      # @api private
+      def call(task, prompt, dir)
+        root = checkout_of(dir)
+        message = "#{format(task, dir: dir)}\n\nRequest: #{prompt}"
+        stdout, status = run(root, message)
+        raise Composer::Agent::Unavailable, "claude exited #{status.exitstatus}: #{stdout}" unless status.success?
+
+        { "note" => JSON.parse(stdout).fetch("result").to_s.lines.first.to_s.strip }
+      rescue JSON::ParserError, KeyError => e
+        raise Composer::Agent::ValidationError, "claude's reply was not the expected envelope: #{e.message}"
+      end
+
+      # Argv spawn, never a shell, so a `claude` shell alias cannot apply.
+      # @api private
+      def run(root, message)
+        Timeout.timeout(TIMEOUT_SECONDS) do
+          Open3.capture2("claude", "-p", "--agent", AGENT, "--output-format", "json",
+                         "--permission-mode", "acceptEdits", stdin_data: message, chdir: root)
+        end
+      rescue Timeout::Error
+        raise Composer::Agent::Unavailable, "claude did not answer within #{TIMEOUT_SECONDS}s"
+      rescue Errno::ENOENT => e
+        raise Composer::Agent::Unavailable, "claude is not on PATH: #{e.message}"
+      end
+
+      # @api private
+      def checkout_of(dir)
+        top, status = Open3.capture2("git", "-C", dir, "rev-parse", "--show-toplevel")
+        raise Composer::Agent::Unavailable, "#{dir} is not inside a git checkout" unless status.success?
+
+        top.strip
+      end
+    end
+  end
+end

data/lib/hecks/composer/adapters/fake_agent.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "FakeAgent" do
+  port "composer_agent"
+end

data/lib/hecks/composer/adapters/fake_agent.rb

@@ -0,0 +1,55 @@
+require_relative "../agent"
+
+module Hecks
+  module Adapters
+    # A scripted `composer_agent`, for specs and for trying the editor with no model behind it.
+    # Each ask is recorded; `draft` and `wire` run a script that may rewrite the workspace's files,
+    # so a test sees the same thing the real agent leaves behind.
+    module FakeAgent
+      class << self
+        # @return [Array<Hash>] every ask, as `{ask:, prompt:, dir:}` in the order made
+        def calls = @calls ||= []
+
+        # @return [#call, nil] takes `(prompt, dir)` and edits files under `dir`; may return a note
+        attr_accessor :edit
+
+        # @return [#call, nil] takes `prompt` and answers an intent
+        attr_accessor :intent
+
+        # Forgets the calls and both scripts.
+        # @return [void]
+        def reset!
+          @calls = []
+          @edit = nil
+          @intent = nil
+        end
+      end
+
+      module_function
+
+      # @param prompt [String] what the author asked for
+      # @param dir [String] the workspace directory
+      # @return [Hash] `"note"` what the script reported
+      def draft(prompt:, dir:) = edited(:draft, prompt, dir)
+
+      # @param prompt [String] what the author asked for
+      # @param dir [String] the workspace directory
+      # @return [Hash] `"note"` what the script reported
+      def wire(prompt:, dir:) = edited(:wire, prompt, dir)
+
+      # @param prompt [String] what the author typed
+      # @return [Hash] `"intent"` what the script answered, `"edit"` without one
+      def classify(prompt:)
+        FakeAgent.calls << { ask: :classify, prompt: prompt, dir: nil }
+        { "intent" => FakeAgent.intent ? FakeAgent.intent.call(prompt) : "edit" }
+      end
+
+      # @api private
+      def edited(ask, prompt, dir)
+        FakeAgent.calls << { ask: ask, prompt: prompt, dir: dir }
+        note = FakeAgent.edit&.call(prompt, dir)
+        { "note" => note.is_a?(String) ? note : "changed nothing" }
+      end
+    end
+  end
+end

data/lib/hecks/composer/adapters/jev.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "Jev" do
+  port "composer_agent"
+end

data/lib/hecks/composer/adapters/jev.rb

@@ -0,0 +1,66 @@
+require "json"
+require "open3"
+require "tmpdir"
+
+require_relative "../agent"
+
+module Hecks
+  module Adapters
+    # `composer_agent` fulfillment for `classify` alone: the `jev` categorizer, which answers a
+    # multiple-choice question about a piece of text. It carries no key of its own; the script
+    # reads one from the environment or from 1Password, so nothing secret is written here.
+    #
+    # `draft` and `wire` are not this adapter's work.
+    module Jev
+      QUESTIONS = {
+        "intent" => {
+          "type"         => "choice",
+          "instructions" => "What is the author of a domain bluebook asking an editor to do?",
+          "criteria"     => {
+            "edit"       => "change what the domain declares: an aggregate, command, attribute, rule or lifecycle",
+            "wire"       => "change how the domain is wired to the outside: persistence, adapters, ports, deployment",
+            "question"   => "explain or answer something about the domain, changing nothing",
+            "new_domain" => "start a new domain from a description of a business"
+          }
+        }
+      }.freeze
+
+      module_function
+
+      # @param prompt [String] what the author typed
+      # @return [Hash] `"intent"` one of {Composer::Agent::INTENTS}
+      # @raise [Composer::Agent::Unavailable] if `jev` is missing, fails or answers nothing
+      def classify(prompt:)
+        answers = ask(prompt)
+        { "intent" => choice(answers["intent"]) }
+      end
+
+      # @api private
+      def ask(prompt)
+        Dir.mktmpdir("hecks-jev") { |dir| JSON.parse(run(prompt, File.join(dir, "questions.json"))) }
+      rescue Errno::ENOENT => e
+        raise Composer::Agent::Unavailable, "jev is not on PATH: #{e.message}"
+      rescue JSON::ParserError => e
+        raise Composer::Agent::Unavailable, "jev's answer was not JSON: #{e.message}"
+      end
+
+      # Runs `jev` on the prompt, with the questions written to `path` beside it.
+      # @api private
+      def run(prompt, path)
+        File.write(path, JSON.generate(QUESTIONS))
+        out, err, status = Open3.capture3(ENV.fetch("HECKS_JEV", "jev"), path, "-", stdin_data: prompt)
+        return out if status.success?
+
+        raise Composer::Agent::Unavailable, "jev exited #{status.exitstatus}: #{err.lines.first}"
+      end
+
+      # `jev` names a choice by its key; accept the bare key or a row that carries it.
+      # @api private
+      def choice(answer)
+        return answer unless answer.is_a?(Hash)
+
+        answer.values_at("choice", "answer", "value", "label").compact.first
+      end
+    end
+  end
+end

data/lib/hecks/composer/agent.rb

@@ -0,0 +1,113 @@
+require_relative "../runtime/registry"
+
+module Hecks
+  module Composer
+    # The agent the Composer asks, on the hecksagon side: one port, `composer_agent`, resolved to
+    # the single adapter a registry holds for it. The caller never sees the adapter, only answers
+    # this module has checked, so a spec can stand a scripted adapter in for the real one.
+    #
+    # Two of the asks change the workspace on disk and answer with a note about what changed:
+    # `draft` edits a bluebook, `wire` edits the `.hecksagon` and `.world` files that bind it. The
+    # third, `classify`, only names what a prompt is asking for.
+    module Agent
+      NAME = "composer_agent".freeze
+      PORT = File.expand_path("ports/composer_agent.port", __dir__).freeze
+      ADAPTERS = File.expand_path("adapters", __dir__).freeze
+
+      # What a prompt can be asking for.
+      INTENTS = %w[edit wire question new_domain].freeze
+
+      # The adapter's answer arrived but was unusable; asking again will not help.
+      class ValidationError < StandardError
+      end
+
+      # Nothing answered (missing binary, dead subprocess, timeout); retry or fall back.
+      class Unavailable < StandardError
+      end
+
+      module_function
+
+      # Asks the agent to change a workspace's bluebooks as the prompt says.
+      #
+      # @param registry [Runtime::Registry] a registry holding the port and one adapter for it
+      # @param prompt [String] what the author asked for
+      # @param dir [String] the workspace directory, whose files the agent edits in place
+      # @return [String] the agent's one-line account of what it changed
+      # @raise [ValidationError] unless the answer is a Hash with a non-blank `"note"`
+      # @raise [Unavailable] if the adapter cannot answer
+      # @raise [Runtime::WiringError] unless exactly one adapter implements the port
+      def draft(registry, prompt:, dir:)
+        note(adapter(registry).draft(prompt: prompt, dir: dir))
+      end
+
+      # Asks the agent to change how a workspace's chapter is wired, never what it declares.
+      #
+      # @param registry [Runtime::Registry] a registry holding the port and one adapter for it
+      # @param prompt [String] what the author asked for
+      # @param dir [String] the workspace directory, whose `.hecksagon` and `.world` files the
+      #   agent edits in place
+      # @return [String] the agent's one-line account of what it changed
+      # @raise [ValidationError] unless the answer is a Hash with a non-blank `"note"`
+      # @raise [Unavailable] if the adapter cannot answer
+      def wire(registry, prompt:, dir:)
+        note(adapter(registry).wire(prompt: prompt, dir: dir))
+      end
+
+      # Names what a prompt is asking for.
+      #
+      # @param registry [Runtime::Registry] a registry holding the port and one adapter for it
+      # @param prompt [String] what the author typed
+      # @return [String] one of `Composer::Agent::INTENTS`
+      # @raise [ValidationError] unless the answer is a Hash whose `"intent"` is one of those
+      # @raise [Unavailable] if the adapter cannot answer
+      def classify(registry, prompt:)
+        answer = adapter(registry).classify(prompt: prompt)
+        intent = answer["intent"] if answer.is_a?(Hash)
+        return intent if INTENTS.include?(intent)
+
+        raise ValidationError, "an intent is one of #{INTENTS.join(", ")}, got #{intent.inspect}"
+      end
+
+      # Builds a registry in which exactly one adapter implements the port.
+      #
+      # @param adapter_file [String] the adapter's `.adapter` declaration
+      # @return [Runtime::Registry] a registry holding the port and that adapter
+      def registry_with(adapter_file)
+        registry = Runtime::Registry.new
+        Hecks.with_registry(registry) do
+          Kernel.load(PORT)
+          Kernel.load(adapter_file)
+        end
+        registry
+      end
+
+      # Finds the single adapter bound to the port.
+      #
+      # @param registry [Runtime::Registry] the registry to search
+      # @return [Module] the adapter implementing the port
+      # @raise [Runtime::WiringError] if none, or more than one, implements the port
+      def adapter(registry)
+        implementations = registry.adapters.values.select { |found| found.port == NAME }
+        return registry.adapter_class(implementations.first.name) if implementations.size == 1
+
+        raise Runtime::WiringError, wiring_refusal(implementations)
+      end
+
+      # @api private
+      def note(answer)
+        text = answer["note"].to_s.strip if answer.is_a?(Hash)
+        return text unless text.nil? || text.empty?
+
+        raise ValidationError, "an agent's answer carries a non-blank \"note\", got #{answer.inspect}"
+      end
+
+      # @api private
+      def wiring_refusal(implementations)
+        return "no adapter implements the #{NAME} port — nothing can edit the draft" 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
+end