hecks 3.4.2 → 3.6.0

data/lib/hecks/projector/docs_projector/behaviour.rb

@@ -0,0 +1,127 @@
+module Hecks
+  module Projector
+    module DocsProjector
+      # The sections of an aggregate or entity that say what can happen to it: lifecycle, verbs
+      # and questions.
+      module Behaviour
+        module_function
+
+        # The lifecycle table of `holder`, or `nil` when it has none.
+        def lifecycle_section(holder, depth)
+          lifecycle = holder.lifecycle or return nil
+
+          rows = lifecycle.transitions.map do |name, transition|
+            ["`#{name}`", "`#{Array(transition.from).join("`, `")}`", "`#{transition.target}`"]
+          end
+          [DocsProjector.h(depth, "Lifecycle (`#{lifecycle.field}`)"), "",
+           "Starts at `#{lifecycle.default}`. A verb not listed here can be issued from any state.", "",
+           DocsProjector.table(%w[verb from to], rows)].join("\n")
+        end
+
+        # The verbs of `holder`, one entry per command, or `nil` when it has none.
+        def verbs_section(holder, depth)
+          commands = holder.commands
+          return nil if commands.empty?
+
+          out = [DocsProjector.h(depth, "Verbs"), ""]
+          commands.each { |command| out << command_entry(command, holder, depth + 1) }
+          out.join("\n")
+        end
+
+        # One command: its goal, role, arguments, refusals, guarantees and events.
+        def command_entry(command, holder, depth)
+          [*command_opening(command, depth), *argument_lines(command, holder),
+           *refusal_lines(refusals_of(command, holder)), *outcome_lines(command), ""].join("\n")
+        end
+
+        # The heading of a command entry, its goal and who issues it.
+        def command_opening(command, depth)
+          out = [DocsProjector.h(depth, "#{command.hecks_name}#{" *(creates)*" if command.creates?}"), ""]
+          out += [command.goal, ""] if command.goal
+          out << "Issued by: **#{command.role}**." if command.role
+          out << ""
+        end
+
+        # The argument table of a command, or no lines when it takes none.
+        def argument_lines(command, holder)
+          arguments = command.attributes
+          return [] if arguments.empty?
+
+          [DocsProjector.table(%w[argument shape needed], command_argument_rows(arguments, holder))]
+        end
+
+        # The "Refused when" list, or no lines when nothing refuses the command.
+        def refusal_lines(refusals)
+          return [] if refusals.empty?
+
+          ["Refused when:", "", *refusals.map { |refusal| "- #{refusal}" }, ""]
+        end
+
+        # What the command guarantees and emits, each only when it has any.
+        def outcome_lines(command)
+          out = []
+          out << "Guarantees: #{command.ensures.map(&:description).join("; ")}." unless command.ensures.empty?
+          out << "Emits `#{command.emits.join("`, `")}`." unless command.emits.empty?
+          out
+        end
+
+        def command_argument_rows(arguments, holder)
+          arguments.map do |attribute|
+            shape = attribute.reference? ? "id of a `#{attribute.type.target_name}`" : Attributes.shape_of(attribute, holder)
+            ["`#{attribute.name}`", shape, attribute.optional? ? "" : "required"]
+          end
+        end
+
+        # Refusals come from the lifecycle edge, the command's `given`s and reference resolution.
+        def refusals_of(command, holder)
+          lifecycle_refusals(command, holder.lifecycle) + reference_refusals(command) +
+            command.givens.map { |given| "not: #{given.description}" }
+        end
+
+        # The refusal for a command issued from a state its lifecycle does not allow.
+        def lifecycle_refusals(command, lifecycle)
+          return [] unless lifecycle
+
+          froms = lifecycle.transitions.filter_map do |name, transition|
+            Array(transition.from) if name.to_s == command.hecks_name
+          end.flatten.uniq
+          return [] if froms.empty?
+
+          ["`#{lifecycle.field}` is anything other than #{froms.map { |f| "`#{f}`" }.join(" or ")}"]
+        end
+
+        # The refusal for each referenced record that may not exist.
+        def reference_refusals(command)
+          command.attributes.select(&:reference?).map do |reference|
+            "no `#{reference.type.target_name}` exists for the id given as `#{reference.name}`"
+          end
+        end
+
+        # The questions of an aggregate or entity, or `nil` when it has none.
+        def queries_section(queries, depth, title)
+          return nil if queries.empty?
+
+          out = [DocsProjector.h(depth, title), ""]
+          queries.each { |query| out.concat(query_lines(query)) }
+          out.join("\n")
+        end
+
+        # One question: its name and parameters, description and filters.
+        def query_lines(query)
+          shape   = query.to_h
+          takes   = Array(shape[:attributes]).map { |a| "`#{a[:name]}`" }.join(", ")
+          out = ["**#{query.hecks_name}**#{" (#{takes})" unless takes.empty?}  ",
+                 (query.description ? "#{query.description}  " : "")]
+          out.concat(filter_lines(shape))
+          out << ""
+        end
+
+        # The "Filters" line of a question, or no line when it filters on nothing.
+        def filter_lines(shape)
+          filters = Array(shape[:wheres]).map { |w| "`#{w[:field]} #{w[:op]} #{w[:value].inspect}`" }
+          filters.empty? ? [] : ["Filters: #{filters.join(", ")}."]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/docs_projector/closing.rb

@@ -0,0 +1,40 @@
+module Hecks
+  module Projector
+    module DocsProjector
+      # The sections that close a chapter's document: the reactions its policies cause and the
+      # sagas it runs.
+      module Closing
+        module_function
+
+        # The closing sections, or `nil` when the chapter has neither policies nor sagas.
+        def call(bluebook, depth)
+          out = reaction_lines(bluebook, depth)
+          bluebook.process_managers.each { |saga| out.concat(saga_lines(saga, depth)) }
+          out.empty? ? nil : out.join("\n")
+        end
+
+        # The table of policies, or no lines when the chapter has none.
+        def reaction_lines(bluebook, depth)
+          return [] if bluebook.policies.empty?
+
+          rows = bluebook.policies.map do |policy|
+            ["`#{policy.on_event}`", "`#{policy.trigger_command}`", policy.target_domain || bluebook.name]
+          end
+          [DocsProjector.h(depth, "Reactions"), "",
+           "These fire on their own. Issuing the verb on the left also causes the one on the right.", "",
+           DocsProjector.table(%w[on\ event dispatches in], rows)]
+        end
+
+        # The lines describing one saga: where it starts, where it ends, what it correlates by
+        # and its states.
+        def saga_lines(saga, depth)
+          shape = saga.to_h
+          [DocsProjector.h(depth, "#{shape[:name]} (a saga)"), "",
+           "Starts on `#{shape[:starts_on]}`, ends on `#{shape[:ends_on]}`, " \
+           "correlated by `#{shape[:correlates_by]}`.", "",
+           "States: #{Array(shape[:states]).map { |s| "`#{s}`" }.join(" → ")}.", ""]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/docs_projector.rb

@@ -22,11 +22,16 @@ module Hecks
 
         out = []
         out << chapter_header(bluebook, depth) unless only
-        Array(aggregates(bluebook, only)).each { |aggregate| out << aggregate_section(aggregate, only ? depth : depth + 1) }
-        out << closing(bluebook, depth + 1) unless only
+        out.concat(aggregate_sections(bluebook, only, depth))
+        out << Closing.call(bluebook, depth + 1) unless only
         "#{out.compact.join("\n").rstrip}\n"
       end
 
+      # One section per aggregate; those of a narrowed document sit at the top heading level.
+      def aggregate_sections(bluebook, only, depth)
+        Array(aggregates(bluebook, only)).map { |aggregate| aggregate_section(aggregate, only ? depth : depth + 1) }
+      end
+
       # An unknown aggregate name is refused rather than answered with an empty document.
       def aggregates(bluebook, only)
         return bluebook.aggregates unless only
@@ -34,232 +39,93 @@ module Hecks
         bluebook.aggregates.find { |aggregate| aggregate.hecks_name == only.to_s } ||
           raise(Runtime::NotFound,
                 "#{bluebook.name} declares no aggregate named #{only.to_s.inspect} — " \
-                "it declares #{bluebook.aggregates.map(&:hecks_name).sort.join(', ')}")
+                "it declares #{bluebook.aggregates.map(&:hecks_name).sort.join(", ")}")
       end
 
-      def h(depth, text) = "#{'#' * depth} #{text}"
+      def h(depth, text) = "#{"#" * depth} #{text}"
 
       def chapter_header(bluebook, depth)
         out = [h(depth, bluebook.name), ""]
         out += ["> #{bluebook.vision}", ""] if bluebook.vision
-        out << "#{bluebook.classification.to_s.capitalize} domain." if bluebook.classification
-        out << "Previously known as `#{bluebook.formerly_known_as}`." if bluebook.formerly_known_as
+        out.concat(classification_lines(bluebook))
         out << ""
-        out << "Aggregates: #{bluebook.aggregates.map { |a| "[#{a.hecks_name}](##{anchor(a.hecks_name)})" }.join(', ')}."
+        out << "Aggregates: #{aggregate_links(bluebook)}."
         out << ""
         out.join("\n")
       end
 
-      def anchor(name) = Naming.snake(name).tr("_", "-")
-
-      def closing(bluebook, depth)
+      # What kind of domain the chapter is and the name it is also known by, when declared.
+      def classification_lines(bluebook)
         out = []
+        out << "#{bluebook.classification.to_s.capitalize} domain." if bluebook.classification
+        out << "Previously known as `#{bluebook.formerly_known_as}`." if bluebook.formerly_known_as
+        out
+      end
 
-        unless bluebook.policies.empty?
-          out << h(depth, "Reactions")
-          out << ""
-          out << "These fire on their own. Issuing the verb on the left also causes the one on the right."
-          out << ""
-          rows = bluebook.policies.map do |policy|
-            ["`#{policy.on_event}`", "`#{policy.trigger_command}`", policy.target_domain || bluebook.name]
-          end
-          out << table(%w[on\ event dispatches in], rows)
-        end
-
-        bluebook.process_managers.each do |saga|
-          shape = saga.to_h
-          out << h(depth, "#{shape[:name]} (a saga)")
-          out << ""
-          out << "Starts on `#{shape[:starts_on]}`, ends on `#{shape[:ends_on]}`, " \
-                 "correlated by `#{shape[:correlates_by]}`."
-          out << ""
-          out << "States: #{Array(shape[:states]).map { |s| "`#{s}`" }.join(' → ')}."
-          out << ""
-        end
-
-        out.empty? ? nil : out.join("\n")
+      # Each aggregate's name as a link to its section.
+      def aggregate_links(bluebook)
+        bluebook.aggregates.map { |a| "[#{a.hecks_name}](##{anchor(a.hecks_name)})" }.join(", ")
       end
 
-      def aggregate_section(aggregate, depth)
-        out = [h(depth, aggregate.hecks_name), ""]
-        out += [aggregate.description, ""] if aggregate.description
+      def anchor(name) = Naming.snake(name).tr("_", "-")
 
-        out << "Identified by `#{aggregate.identity_heads.join('`, `')}`." unless aggregate.identity_heads.empty?
-        refs = aggregate.attributes.select(&:reference?)
-        out << "References #{refs.map { |r| "`#{r.type.target_name}`" }.join(', ')}." unless refs.empty?
+      def aggregate_section(aggregate, depth)
+        out = opening_lines(depth, aggregate.hecks_name, aggregate.description)
+        out.concat(identity_lines(aggregate))
         out << ""
-
-        out << attributes_table(aggregate)
-        out << lifecycle_section(aggregate, depth + 1)
-        out << verbs_section(aggregate, depth + 1)
-        out << queries_section(aggregate.queries, depth + 1, "Questions you can ask")
-
+        out.concat(holder_parts(aggregate, depth + 1))
         aggregate.entities.each { |entity| out << entity_section(aggregate, entity, depth + 1) }
 
         out.compact.join("\n")
       end
 
-      def entity_section(aggregate, entity, depth)
-        out = [h(depth, "#{entity.hecks_name} (within #{aggregate.hecks_name})"), ""]
-        out += [entity.description, ""] if entity.description
-        # An entity has no door of its own; its verbs go through the holding aggregate.
-        out << "Addressed through its holder — `#{aggregate.hecks_name}.#{entity.hecks_name}.<Verb>`, " \
-               "passing the #{aggregate.hecks_name}'s `id` and this element's " \
-               "`#{entity.identity_heads.join('`, `')}`."
-        out << ""
-        out << attributes_table(entity)
-        out << lifecycle_section(entity, depth + 1)
-        out << verbs_section(entity, depth + 1)
-        out << queries_section(entity.queries, depth + 1, "Questions you can ask")
-        out.compact.join("\n")
-      end
-
-      def attributes_table(holder)
-        attributes = holder.attributes.reject(&:reference?)
-        return nil if attributes.empty?
-
-        rows = attributes.map do |attribute|
-          ["`#{attribute.name}`", shape_of(attribute, holder), rules_of(attribute, holder)]
-        end
-        table(%w[attribute shape rules], rows)
-      end
-
-      # A value object's fields, not its name: callers need to know what shape to send.
-      def shape_of(attribute, holder)
-        value_object = value_object_for(attribute, holder)
-        inner =
-          if value_object
-            "{ #{value_object.attributes.map { |f| "#{f.name}: #{f.type}" }.join(', ')} }"
-          else
-            attribute.type.to_s
-          end
-        shape = attribute.list? ? "list of #{inner}" : inner
-        attribute.optional? ? "#{shape} *(optional)*" : shape
-      end
-
-      def rules_of(attribute, holder)
-        value_object = value_object_for(attribute, holder)
-        rules = []
-        rules << "one of #{closed_members(value_object).map { |m| "`#{m}`" }.join(', ')}" if closed_members(value_object).any?
-        Array(value_object&.attributes).each do |field|
-          rules << "`#{field.name}` matches `#{field.pattern}`" if field.pattern
-          rules << "`#{field.name}` defaults to `#{field.default.inspect}`" unless field.default.nil?
-        end
-        rules += Array(value_object&.invariants).map(&:description)
-        rules << "defaults to `#{attribute.default.inspect}`" unless attribute.default.nil?
-        rules.empty? ? "" : rules.join("; ")
-      end
-
-      def closed_members(value_object)
-        return [] unless value_object&.closed_set?
-
-        value_object.members.flat_map(&:values).uniq
-      end
-
-      # An entity holds no value objects; its types are declared on the owning aggregate.
-      def value_object_for(attribute, holder)
-        scopes = [holder, holder.respond_to?(:hecks_owner) ? holder.hecks_owner : nil].compact
-        scopes.each do |scope|
-          next unless scope.respond_to?(:value_objects)
-
-          found = scope.value_objects.find { |v| v.hecks_name == attribute.type.to_s }
-          return found if found
-        end
-        nil
+      # A section's heading, then its description when it has one.
+      def opening_lines(depth, title, description)
+        out = [h(depth, title), ""]
+        out += [description, ""] if description
+        out
       end
 
-      def lifecycle_section(holder, depth)
-        lifecycle = holder.lifecycle or return nil
-
-        rows = lifecycle.transitions.map do |name, transition|
-          ["`#{name}`", "`#{Array(transition.from).join('`, `')}`", "`#{transition.target}`"]
-        end
-        [h(depth, "Lifecycle (`#{lifecycle.field}`)"), "",
-         "Starts at `#{lifecycle.default}`. A verb not listed here can be issued from any state.", "",
-         table(%w[verb from to], rows)].join("\n")
+      # What identifies an aggregate and which records it references.
+      def identity_lines(aggregate)
+        out = []
+        out << "Identified by `#{aggregate.identity_heads.join("`, `")}`." unless aggregate.identity_heads.empty?
+        refs = aggregate.attributes.select(&:reference?)
+        out << "References #{refs.map { |r| "`#{r.type.target_name}`" }.join(", ")}." unless refs.empty?
+        out
       end
 
-      def verbs_section(holder, depth)
-        commands = holder.commands
-        return nil if commands.empty?
-
-        out = [h(depth, "Verbs"), ""]
-        commands.each { |command| out << command_entry(command, holder, depth + 1) }
-        out.join("\n")
+      # The attribute table, lifecycle, verbs and questions of an aggregate or entity.
+      def holder_parts(holder, depth)
+        [Attributes.table_for(holder), Behaviour.lifecycle_section(holder, depth),
+         Behaviour.verbs_section(holder, depth),
+         Behaviour.queries_section(holder.queries, depth, "Questions you can ask")]
       end
 
-      def command_entry(command, holder, depth)
-        out = [h(depth, "#{command.hecks_name}#{' *(creates)*' if command.creates?}"), ""]
-        out += [command.goal, ""] if command.goal
-        out << "Issued by: **#{command.role}**." if command.role
-        out << ""
-
-        arguments = command.attributes
-        out << table(%w[argument shape needed], command_argument_rows(arguments, holder)) unless arguments.empty?
-
-        refusals = refusals_of(command, holder)
-        unless refusals.empty?
-          out << "Refused when:"
-          out << ""
-          refusals.each { |refusal| out << "- #{refusal}" }
-          out << ""
-        end
-
-        out << "Guarantees: #{command.ensures.map(&:description).join('; ')}." unless command.ensures.empty?
-        out << "Emits `#{command.emits.join('`, `')}`." unless command.emits.empty?
+      def entity_section(aggregate, entity, depth)
+        out = opening_lines(depth, "#{entity.hecks_name} (within #{aggregate.hecks_name})", entity.description)
+        out << entity_addressing(aggregate, entity)
         out << ""
-        out.join("\n")
-      end
-
-      def command_argument_rows(arguments, holder)
-        arguments.map do |attribute|
-          shape = attribute.reference? ? "id of a `#{attribute.type.target_name}`" : shape_of(attribute, holder)
-          ["`#{attribute.name}`", shape, attribute.optional? ? "" : "required"]
-        end
-      end
-
-      # Refusals come from the lifecycle edge, the command's `given`s and reference resolution.
-      def refusals_of(command, holder)
-        refusals = []
-
-        lifecycle = holder.lifecycle
-        froms = lifecycle && lifecycle.transitions.filter_map do |name, transition|
-          Array(transition.from) if name.to_s == command.hecks_name
-        end.flatten.uniq
-        if froms && !froms.empty?
-          refusals << "`#{lifecycle.field}` is anything other than #{froms.map do |f|
-            "`#{f}`"
-          end.join(' or ')}"
-        end
-
-        command.attributes.select(&:reference?).each do |reference|
-          refusals << "no `#{reference.type.target_name}` exists for the id given as `#{reference.name}`"
-        end
-
-        refusals + command.givens.map { |given| "not: #{given.description}" }
+        out.concat(holder_parts(entity, depth + 1))
+        out.compact.join("\n")
       end
 
-      def queries_section(queries, depth, title)
-        return nil if queries.empty?
-
-        out = [h(depth, title), ""]
-        queries.each do |query|
-          shape   = query.to_h
-          takes   = Array(shape[:attributes]).map { |a| "`#{a[:name]}`" }.join(", ")
-          out << "**#{query.hecks_name}**#{" (#{takes})" unless takes.empty?}  "
-          out << (query.description ? "#{query.description}  " : "")
-          filters = Array(shape[:wheres]).map { |w| "`#{w[:field]} #{w[:op]} #{w[:value].inspect}`" }
-          out << "Filters: #{filters.join(', ')}." unless filters.empty?
-          out << ""
-        end
-        out.join("\n")
+      # An entity has no door of its own; its verbs go through the holding aggregate.
+      def entity_addressing(aggregate, entity)
+        "Addressed through its holder — `#{aggregate.hecks_name}.#{entity.hecks_name}.<Verb>`, " \
+          "passing the #{aggregate.hecks_name}'s `id` and this element's " \
+          "`#{entity.identity_heads.join("`, `")}`."
       end
 
       def table(headers, rows)
-        lines = ["| #{headers.join(' | ')} |", "|#{headers.map { '---' }.join('|')}|"]
-        rows.each { |row| lines << "| #{row.join(' | ')} |" }
+        lines = ["| #{headers.join(" | ")} |", "|#{headers.map { "---" }.join("|")}|"]
+        rows.each { |row| lines << "| #{row.join(" | ")} |" }
         (lines + [""]).join("\n")
       end
     end
   end
 end
+
+require_relative "docs_projector/attributes"
+require_relative "docs_projector/behaviour"
+require_relative "docs_projector/closing"

data/lib/hecks/projector/exporter/bindings.rb

@@ -0,0 +1,174 @@
+module Hecks
+  module Projector
+    module Exporter
+      # Which chapter of a registry answers each capability a domain attaches (authorization,
+      # membership, identity, newsletter, registrations, payments): a per-deployment binding fact,
+      # not part of the declared IR. Each answers `{}` when nothing the domain attaches provides it.
+      module Bindings
+        # Which chapter this domain's role checks resolve against
+        # (`Registry#authorization_provider_for`); `{}` if none does.
+        #
+        # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
+        # @param domain_name [String] the domain to export the authorization binding for
+        # @return [Hash{Symbol => String, nil}] `:provider` (name), `:grant`, `:assignments`
+        #   (both provided-verb names), and `:assignment_aggregate` (`:assignments`' own
+        #   leading aggregate name); `{}` if nothing this domain attaches provides
+        #   authorization
+        def authorization(registry, domain_name)
+          provider = registry.authorization_provider_for(domain_name)
+          return {} unless provider
+
+          capability = Bluebook::Capabilities::AUTHORIZATION
+          assignments = provider.provided_verb(capability, :assignments)
+          {
+            provider:             provider.name,
+            grant:                provider.provided_verb(capability, :grant),
+            assignments:          assignments,
+            assignment_aggregate: aggregate_of(assignments)
+          }
+        end
+
+        # Which chapter answers "who may sign in" (`Registry#membership_provider_for`),
+        # with the membership aggregate named off `admit`; `{}` if none does.
+        #
+        # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
+        # @param domain_name [String] the domain to export the membership binding for
+        # @return [Hash{Symbol => String, nil}] `:provider` (name), `:admit`, `:grant`,
+        #   `:people` (qualified verbs), and `:aggregate` (`:admit`'s own leading
+        #   aggregate name); `{}` if nothing this domain attaches provides membership
+        def membership(registry, domain_name)
+          provider = registry.membership_provider_for(domain_name)
+          return {} unless provider
+
+          verbs = verbs_of(provider, Bluebook::Capabilities::MEMBERSHIP, :admit, :grant, :people)
+          { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:admit]) }
+        end
+
+        # Which chapter answers "who is this authenticated pair"; `{}` if none does.
+        # Breaking in 2.0: Link's reference field is `identity`, never `identity_id`.
+        #
+        # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
+        # @param domain_name [String] the domain to export the identity binding for
+        # @return [Hash{Symbol => String, nil}] `:provider` (name), `:register`, `:link`,
+        #   `:resolve` (qualified verbs); `{}` if nothing this domain attaches provides identity
+        def identity(registry, domain_name)
+          provider = registry.identity_provider_for(domain_name)
+          return {} unless provider
+
+          capability = Bluebook::Capabilities::IDENTITY
+          {
+            provider: provider.name,
+            register: provider.provided_verb(capability, :register),
+            link:     provider.provided_verb(capability, :link),
+            resolve:  provider.provided_verb(capability, :resolve)
+          }
+        end
+
+        # Which chapter answers the guest newsletter signup
+        # (`Registry#newsletter_provider_for`); `{}` if none does.
+        #
+        # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
+        # @param domain_name [String] the domain to export the newsletter binding for
+        # @return [Hash{Symbol => String, nil}] `:provider` (name), `:subscribe`, `:add_name`,
+        #   `:confirm`, `:unsubscribe` (qualified verbs), and `:aggregate` (`:subscribe`'s own
+        #   leading qualified aggregate name); `{}` if nothing this domain attaches provides
+        #   newsletter
+        def newsletter(registry, domain_name)
+          provider = registry.newsletter_provider_for(domain_name)
+          return {} unless provider
+
+          verbs = verbs_of(provider, Bluebook::Capabilities::NEWSLETTER,
+                           :subscribe, :add_name, :confirm, :unsubscribe)
+          { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:subscribe]) }
+        end
+
+        # Which chapter answers sending a newsletter issue
+        # (`Registry#newsletter_issues_provider_for`); `{}` if none does.
+        #
+        # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
+        # @param domain_name [String] the domain to export the issue-sending binding for
+        # @return [Hash{Symbol => String, nil}] `:provider` (name), `:send_issue`,
+        #   `:record_delivery` (qualified verbs), `:issue_aggregate` and `:delivery_aggregate`
+        #   (each verb's own leading qualified aggregate name); `{}` if nothing this domain
+        #   attaches provides newsletter_issues
+        def newsletter_issues(registry, domain_name)
+          provider = registry.newsletter_issues_provider_for(domain_name)
+          return {} unless provider
+
+          verbs = verbs_of(provider, Bluebook::Capabilities::NEWSLETTER_ISSUES, :send_issue, :record_delivery)
+          { provider: provider.name, **verbs,
+            **aggregates_of(verbs, issue_aggregate: :send_issue, delivery_aggregate: :record_delivery) }
+        end
+
+        # Which chapter answers scheduling sessions and taking registrations
+        # (`Registry#registrations_provider_for`); `{}` if none does.
+        #
+        # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
+        # @param domain_name [String] the domain to export the registrations binding for
+        # @return [Hash{Symbol => String, nil}] `:provider` (name), `:schedule`, `:request`
+        #   (qualified verbs), `:event_aggregate` and `:registration_aggregate` (each verb's own
+        #   leading qualified aggregate name); `{}` if nothing this domain attaches provides
+        #   registrations
+        def registrations(registry, domain_name)
+          provider = registry.registrations_provider_for(domain_name)
+          return {} unless provider
+
+          verbs = verbs_of(provider, Bluebook::Capabilities::REGISTRATIONS, :schedule, :request)
+          { provider: provider.name, **verbs,
+            **aggregates_of(verbs, event_aggregate: :schedule, registration_aggregate: :request) }
+        end
+
+        # Which chapter owns the payment-processor connection
+        # (`Registry#payment_connection_provider_for`); `{}` if none does.
+        #
+        # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
+        # @param domain_name [String] the domain to export the payment-connection binding for
+        # @return [Hash{Symbol => String, nil}] `:provider` (name), one qualified verb per
+        #   contract key (`:connect`, `:reconnect`, `:disconnect`, `:suspend`, `:resume`,
+        #   `:enable`, `:disable`) and `:aggregate` (`:connect`'s own leading qualified
+        #   aggregate name); `{}` if nothing this domain attaches provides payment_connection
+        def payment_connection(registry, domain_name)
+          provider = registry.payment_connection_provider_for(domain_name)
+          return {} unless provider
+
+          capability = Bluebook::Capabilities::PAYMENT_CONNECTION
+          verbs = verbs_of(provider, capability, *Bluebook::Capabilities::CONTRACTS.fetch(capability).keys)
+          { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:connect]) }
+        end
+
+        # Which chapter takes payments (`Registry#payments_provider_for`);
+        # `{}` if none does.
+        #
+        # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
+        # @param domain_name [String] the domain to export the payments binding for
+        # @return [Hash{Symbol => String, nil}] `:provider` (name), `:initiate`, `:succeeded`,
+        #   `:failed` (qualified verbs), and `:aggregate` (`:initiate`'s own leading qualified
+        #   aggregate name); `{}` if nothing this domain attaches provides payments
+        def payments(registry, domain_name)
+          provider = registry.payments_provider_for(domain_name)
+          return {} unless provider
+
+          verbs = verbs_of(provider, Bluebook::Capabilities::PAYMENTS, :initiate, :succeeded, :failed)
+          { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:initiate]) }
+        end
+
+        private
+
+        # The qualified verb `provider` supplies for each of `keys` under `capability`.
+        def verbs_of(provider, capability, *keys)
+          keys.to_h { |key| [key, provider.provided_verb(capability, key)] }
+        end
+
+        # Each name in `names` mapped to the leading aggregate of the verb its key names in `verbs`.
+        def aggregates_of(verbs, names)
+          names.transform_values { |key| aggregate_of(verbs[key]) }
+        end
+
+        # The leading aggregate name of a qualified verb, or `nil` when there is no verb.
+        def aggregate_of(verb)
+          verb&.split(".")&.first
+        end
+      end
+    end
+  end
+end