hecks 5.0.0 → 7.0.0

data/lib/hecks/bluebook/capabilities.rb

@@ -1,11 +1,17 @@
 require_relative "capabilities/attribute_values"
+require_relative "capabilities/package_declared"
 
 module Hecks
   module Bluebook
-    # What a chapter may declare it provides — trusted in place of a literal
-    # chapter-name check by role checks, adapters and the fuzzer.
+    # What a bluebook may declare it provides — trusted in place of a literal
+    # bluebook-name check by role checks, adapters and the fuzzer.
+    #
+    # The language defines a contract only for the capabilities Hecks itself consumes. Any other
+    # `provides` name is the package's own: its keys are checked to name something the bluebook
+    # declares (`PackageDeclared`), and whoever reads the capability checks the keys it needs.
     module Capabilities
       extend AttributeValues
+      extend PackageDeclared
 
       AUTHORIZATION = "authorization".freeze
       # Who may sign in and with what role, resolved by declaration rather
@@ -14,61 +20,31 @@ module Hecks
       # A stable organizational identity, recognised by declaration rather
       # than the literal name "Identity".
       IDENTITY = "identity".freeze
-      # Guest newsletter signups, recognised by declaration rather than the
-      # literal chapter name "Newsletter".
-      NEWSLETTER = "newsletter".freeze
-      # Sending an issue to confirmed subscribers; kept separate from
-      # `NEWSLETTER` so a signup-only chapter declares nothing more.
-      NEWSLETTER_ISSUES = "newsletter_issues".freeze
-
-      # Taking a payment through an external processor, recognised by
-      # declaration rather than the literal name "Payments"; the two
-      # verdicts are port operations, not commands.
-      PAYMENTS = "payments".freeze
-
-      # Scheduling sessions and taking registrations, recognised by
-      # declaration rather than the literal aggregate names.
-      REGISTRATIONS = "registrations".freeze
-
-      # A business's connection to its payment processor, recognised by
-      # declaration rather than the literal name "PaymentConnection".
-      PAYMENT_CONNECTION = "payment_connection".freeze
-
-      # The checkout boundary in front of a payment processor: how long a
-      # signed webhook stays fresh and how long a session holds its seat,
-      # recognised by declaration rather than the literal chapter name.
-      CHECKOUT = "checkout".freeze
 
       # Marking a domain's attributes sensitive and reading the markings back, recognised by
-      # declaration rather than the literal chapter name "Privacy".
+      # declaration rather than the literal bluebook name "Privacy".
       PRIVACY = "privacy".freeze
 
       # A subject's key record, shredded to erase them, recognised by declaration rather than the
       # literal names "Privacy" and "SubjectKey".
       SUBJECT_KEYS = "subject_keys".freeze
 
-      # The kinds of contract entry a capability may name: `:command` and
-      # `:query` ("Aggregate.Name"), `:port_operation` ("Aggregate.Port.Operation")
-      # and `:mark` ("Aggregate.mark_name", the states of that aggregate's
-      # lifecycle mark) and `:duration` ("Aggregate.attribute", the whole-seconds
-      # `default:` of that attribute, ADR 0098). `:mark` and `:duration` entries are
-      # optional; every other entry is required.
-      #
-      # ADR 0099 adds two more optional kinds: `:text` ("Aggregate.attribute", the string
-      # `default:` of that attribute, a word the domain owns) and `:attribute`
-      # ("Aggregate.attribute", the attribute's own name, for the host to read a field by).
-      OPTIONAL_KINDS = %i[mark duration text attribute].freeze
-
+      # The contract of each capability the language defines: every key a `provides` row must
+      # name, and whether it names a command or a query ("Aggregate.Name").
       CONTRACTS = {
-        AUTHORIZATION      => {
+        AUTHORIZATION => {
           # every assignment an actor holds, current or historical
-          assignments: :query,
+          assignments:      :query,
+          # the assignments an actor holds right now: those that have not ended
+          live_assignments: :query,
           # the command that grants an actor a role
-          grant:       :command,
-          # every grant of one role acting as another
-          transitions: :query
+          grant:            :command,
+          # every grant of one role acting as another, current or historical
+          transitions:      :query,
+          # the grants of one role acting as another that have not ended
+          live_transitions: :query
         }.freeze,
-        MEMBERSHIP         => {
+        MEMBERSHIP    => {
           # recognize a person who may eventually sign in
           admit:  :command,
           # grant an admitted person a role (the access-grant half)
@@ -76,7 +52,7 @@ module Hecks
           # every admitted person, for the admin listing
           people: :query
         }.freeze,
-        IDENTITY           => {
+        IDENTITY      => {
           # mint a stable identity, independent of how it authenticated
           register: :command,
           # associate an (issuer, subject) pair with that identity
@@ -84,107 +60,31 @@ module Hecks
           # look up the identity an authenticated pair resolves to
           resolve:  :query
         }.freeze,
-        NEWSLETTER         => {
-          # a guest signs up; the aggregate it names is the subscriber
-          subscribe:             :command,
-          # attach a display name to an existing subscriber
-          add_name:              :command,
-          # a subscriber confirms their address from the emailed link
-          confirm:               :command,
-          # a subscriber leaves from the emailed link
-          unsubscribe:           :command,
-          # Optional: the subscriber states that await the emailed confirm
-          # link, spelled "Subscriber.awaiting_confirmation"
-          awaiting_confirmation: :mark,
-          # Optional: the subscriber states that receive each issue sent
-          receives_issues:       :mark,
-          # Optional: the subscriber states of someone who has left
-          left:                  :mark,
-          # Optional: how many seconds the emailed confirm link stays valid,
-          # spelled "Subscriber.confirm_window"
-          confirm_window:        :duration,
-          # Optional: how many seconds an emailed unsubscribe link stays valid
-          unsubscribe_window:    :duration
-        }.freeze,
-        NEWSLETTER_ISSUES  => {
-          # mark an issue sent; the issue aggregate is the one it names
-          send_issue:      :command,
-          # record one email handed to the mail provider; the delivery
-          # aggregate is the one it names
-          record_delivery: :command
-        }.freeze,
-        PAYMENTS           => {
-          # start a payment; the aggregate it names is the payment
-          initiate:     :command,
-          # the processor reports the money arrived
-          succeeded:    :port_operation,
-          # the processor reports the payment failed or expired
-          failed:       :port_operation,
-          # Optional: the lifecycle states of the payment that hold a seat,
-          # spelled "Payment.holds_seat" (Aggregate.mark_name); resolves to the
-          # states of that aggregate's lifecycle `mark :holds_seat`
-          holds_seat:   :mark,
-          # Optional: the failure reason a lapsed checkout hold records, spelled
-          # "Payment.lapse_reason" (the string `default:` of that attribute)
-          lapse_reason: :text
-        }.freeze,
-        REGISTRATIONS      => {
-          # schedule a session; the aggregate it names is the event
-          schedule:      :command,
-          # a guest asks for a place; the aggregate it names is the registration
-          request:       :command,
-          # Optional: the registration attribute that stamps when it was asked for,
-          # spelled "Registration.requested_at"
-          registered_at: :attribute,
-          # Optional: the registration states that give a seat back, spelled
-          # "Registration.frees_seat" (Aggregate.mark_name); resolves to the
-          # states of that aggregate's lifecycle `mark :frees_seat`
-          frees_seat:    :mark
-        }.freeze,
-        PAYMENT_CONNECTION => {
-          # link the processor account; the aggregate it names is the connection
-          connect:    :command,
-          # link a different processor account after a disconnect
-          reconnect:  :command,
-          # drop the link
-          disconnect: :command,
-          # pause the connection without dropping it
-          suspend:    :command,
-          # lift a pause
-          resume:     :command,
-          # switch taking payments on
-          enable:     :command,
-          # switch taking payments off
-          disable:    :command
-        }.freeze,
-        PRIVACY            => {
+        PRIVACY       => {
           # flag one attribute of a domain sensitive
           mark_sensitive: :command,
           # every marking of one domain, for masking a read
           markings_for:   :query
         }.freeze,
-        SUBJECT_KEYS       => {
+        SUBJECT_KEYS  => {
           # the key record of one subject, if any
           key_for: :query,
           # record the subject's key as destroyed
           shred:   :command
-        }.freeze,
-        CHECKOUT           => {
-          # Optional: how many seconds either side of now a signed webhook's
-          # timestamp may sit, spelled "WebhookReceipt.tolerance"
-          webhook_tolerance: :duration,
-          # Optional: how many seconds a session holds its seat
-          session_hold:      :duration
         }.freeze
       }.freeze
 
       # The keys a capability's `provides` must name.
       #
       # @param capability [String] a `CONTRACTS` key
-      # @return [Array<Symbol>] the keys whose kind is not optional
-      def self.required_keys(capability)
-        CONTRACTS.fetch(capability).reject { |_, kind| OPTIONAL_KINDS.include?(kind) }.keys
-      end
+      # @return [Array<Symbol>] every key of its contract
+      def self.required_keys(capability) = CONTRACTS.fetch(capability).keys
+
+      # Whether the language defines `capability`'s contract, rather than the package providing it.
+      #
+      # @param capability [String, Symbol] a capability's name
+      # @return [Boolean] whether `CONTRACTS` holds it
+      def self.language_defined?(capability) = CONTRACTS.key?(capability.to_s)
     end
   end
 end

data/lib/hecks/bluebook/command.rb

@@ -50,6 +50,10 @@ module Hecks
       emits_ir(
         name:       :hecks_name,
         role:       :role,
+        # Every role that may run the command, when more than one may; `role` is then the first.
+        roles:      -> { roles.size > 1 ? roles : Hecks::IR::OMIT },
+        # Who a launcher lists the command for; absent when the command declares none.
+        audience:   -> { audience.empty? ? Hecks::IR::OMIT : audience },
         goal:       :goal,
         references: :references,
         attributes: many(:attributes),
@@ -60,31 +64,48 @@ module Hecks
         emits:      :emits,
         # The lifecycle state this command is admissible from: a guard, not a transition.
         from:       -> { from },
-        provenance: :provenance
+        provenance: :provenance,
+        # Safe to deliver twice; the saga redrive reads it for a dispatch left unsettled.
+        idempotent: -> { idempotent? },
+        # Lets this command's own record through a boot whose shape no era holds yet.
+        mints_era:  -> { mints_era? }
       )
 
       # Every optional declared field and what it holds when the declaration omits it.
       FIELD_DEFAULTS = {
-        role: nil, goal: nil, attributes: [], givens: [], ensures: [], needs: [],
-        mutations: [], emits: [], references: nil, from: nil, provenance: nil
+        role: nil, roles: [], audience: [], goal: nil, attributes: [], givens: [], ensures: [], needs: [],
+        mutations: [], emits: [], references: nil, from: nil, provenance: nil, idempotent: false,
+        mints_era: false
       }.freeze
 
       class << self
         attr_reader :role, :goal, :attributes, :givens, :ensures, :needs, :mutations, :emits, :references,
-                    :from, :provenance
+                    :from, :provenance, :idempotent, :mints_era
+
+        # @return [Boolean] whether a second delivery leaves the state a first one did
+        def idempotent? = @idempotent ? true : false
+
+        # @return [Boolean] whether this command's own record may be written through an unminted boot
+        def mints_era? = @mints_era ? true : false
+
+        # @return [Array<String>] every role that may run it when more than one may, else empty
+        def roles = @roles || []
+
+        # @return [Array<String>] who a launcher lists it for, else empty (a person and an agent)
+        def audience = @audience || []
 
         # Mints one command as its own anonymous subclass of the class `declare` is called on.
         #
         # @param name [String, Symbol] the command's declared name
-        # @param role [String, nil] the declared role text; `goal` is the goal text
+        # @param role [String, nil] the declared role; `roles` all of them, `audience` who it is listed for
         # @param attributes [Array<Bluebook::Attribute>] the declared arguments
         # @param givens [Array<Bluebook::Given>] the declared preconditions
         # @param ensures [Array<Bluebook::Given>] the postconditions; `needs` the facts it supplies
-        # @param mutations [Array<Bluebook::Mutation>] the state changes it applies
-        # @param emits [Array<String>] the event names it may emit
+        # @param mutations [Array<Bluebook::Mutation>] its state changes; `emits` the event names
         # @param references [String, Symbol, nil] the aggregate its `reference_to` addresses
         # @param from [String, Array<String>, nil] the lifecycle states it is admissible from
         # @param provenance [Object, nil] the declared canonical source, as written
+        # @param idempotent [Boolean] whether a second delivery changes nothing
         def declare(name:, **given)
           fields = KeywordFields.fill(given, FIELD_DEFAULTS)
           verb = Class.new(self)
@@ -104,6 +125,11 @@ module Hecks
           end
           settle
         end
+
+        # Every role that may run the command: its `roles` when several may, else its one `role`.
+        #
+        # @return [Array<String>] empty when the command declares no role
+        def role_set = roles.size > 1 ? roles : [role].compact.map(&:to_s)
       end
     end
   end

data/lib/hecks/bluebook/context_map.rb

@@ -0,0 +1,104 @@
+module Hecks
+  module Bluebook
+    # A context map as data: the contexts a system holds, who owns each, and how pairs of them
+    # relate (ADR 0135). Declared first; `ModelCheck::ContextMapChecks` holds the wiring to it.
+    #
+    # How a map is written down (its file kind and builder) is a separate decision. This holds
+    # only what any spelling of it must say.
+    class ContextMap
+      # The relationship kinds a map may declare. `separate_ways` is not one: it is the absence
+      # of a relationship, kept in {#separate_ways}.
+      KINDS = %i[customer_supplier conformist anticorruption_layer shared_kernel open_host
+                 partnership].freeze
+
+      # The kind of the derived edge that an `attaches` makes.
+      ATTACH = "shared_kernel".freeze
+
+      # One context: its name and the team that owns it.
+      Context = Struct.new(:name, :team, keyword_init: true)
+
+      # One declared relationship between two contexts.
+      #
+      # `upstream` supplies and `downstream` consumes. `published` lists the upstream events a
+      # downstream may depend on; `shared` the names two contexts hold in common (shared kernel).
+      # `acknowledged` maps a finding kind about the relationship to the reason it is allowed.
+      # `implied` marks one the wiring states and no one wrote down (an `attaches`, ADR 0155).
+      Relationship = Struct.new(:upstream, :downstream, :kind, :published, :shared, :acknowledged, :implied,
+                                keyword_init: true) do
+        # @return [Array(String, String)] the two contexts, sorted, whichever way the arrow runs
+        def pair = [upstream, downstream].sort
+
+        # @return [Boolean] whether the relationship allows a finding of this kind
+        def acknowledges?(finding) = (acknowledged || {}).key?(finding.to_sym)
+      end
+
+      attr_reader :name, :contexts, :relationships, :separate_ways
+
+      # @param name [String] the system the map covers
+      # @param contexts [Array<Context>] every context the system holds
+      # @param relationships [Array<Relationship>] the declared relationships
+      # @param separate_ways [Array<Array(String, String)>] pairs declared apart
+      # @raise [ArgumentError] on an unknown kind, or a relationship or pair naming an undeclared
+      #   context
+      def initialize(name:, contexts: [], relationships: [], separate_ways: [])
+        @name          = name.to_s
+        @contexts      = contexts
+        @relationships = relationships
+        @separate_ways = separate_ways.map { |pair| pair.map(&:to_s).sort }
+        refuse_unknown_kinds!
+        refuse_undeclared_contexts!
+      end
+
+      # @return [Array<String>] the declared contexts' names
+      def context_names = contexts.map { |context| context.name.to_s }
+
+      # @param left [String] a context's name
+      # @param right [String] another context's name
+      # @return [Array<Relationship>] the relationships declared between them, either way round
+      def relationships_between(left, right)
+        pair = [left.to_s, right.to_s].sort
+        relationships.select { |relationship| relationship.pair == pair }
+      end
+
+      # @return [Boolean] whether the map declares the two contexts apart
+      def separate?(left, right) = separate_ways.include?([left.to_s, right.to_s].sort)
+
+      # The map with each attach the wiring makes read as a `conformist` relationship, unless the
+      # map already says something about that pair or declares it apart (ADR 0155).
+      #
+      # @param edges [Array<Hash>] `Projections::ContextRelationships.call`
+      # @return [ContextMap] this map plus its implied relationships, or itself when none apply
+      def implying(edges)
+        implied = edges.select { |edge| edge[:kind] == ATTACH }.filter_map { |edge| implied_from(edge) }
+        return self if implied.empty?
+
+        self.class.new(name: name, contexts: contexts, relationships: relationships + implied.uniq,
+                       separate_ways: separate_ways)
+      end
+
+      private
+
+      def implied_from(edge)
+        return if separate?(edge[:from], edge[:to]) || relationships_between(edge[:from], edge[:to]).any?
+
+        Relationship.new(upstream: edge[:to], downstream: edge[:from], kind: :conformist, implied: true)
+      end
+
+      def refuse_unknown_kinds!
+        unknown = relationships.map(&:kind).uniq - KINDS
+        return if unknown.empty?
+
+        raise ArgumentError, "unknown relationship kind #{unknown.first.inspect} (known: #{KINDS.inspect})"
+      end
+
+      def refuse_undeclared_contexts!
+        named = (relationships.flat_map { |relationship| [relationship.upstream, relationship.downstream] } +
+                 separate_ways.flatten).map(&:to_s).uniq
+        missing = named - context_names
+        return if missing.empty?
+
+        raise ArgumentError, "#{name} relates #{missing.join(", ")}, which it does not declare as a context"
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/{chapter.rb → declaration.rb}

@@ -1,14 +1,14 @@
-require_relative "behaviour/chapter"
+require_relative "behaviour/declaration"
 require_relative "capabilities"
 require_relative "keyword_fields"
 require_relative "../ir"
 
 module Hecks
   module Bluebook
-    # The chapter, distinct from the `Bluebook` namespace it lives in.
-    class Chapter
+    # The bluebook, distinct from the `Bluebook` namespace it lives in.
+    class Declaration
       include Construct
-      include Behaviour::Chapter
+      include Behaviour::Declaration
       include Hecks::IR
 
       # The IR shape's own version — bump only when `to_h`'s shape changes,
@@ -21,12 +21,12 @@ module Hecks
         version:           :version,
         vision:            :vision,
         classification:    :classification,
-        # Present (possibly nil) rather than silently absent, so two chapters
+        # Present (possibly nil) rather than silently absent, so two bluebooks
         # differing only by their old name can't hash identically at the
         # meta-validator's cache key (`SHA256(JSON(bluebook.to_h))`).
         formerly_known_as: :formerly_known_as,
-        # The Ruby module the chapter's constants install under, when it is not the chapter's
-        # own name (the Hecks domain nests under `Hecks::Domain`); nil for every other chapter.
+        # The Ruby module the bluebook's constants install under, when it is not the bluebook's
+        # own name (the Hecks domain nests under `Hecks::Domain`); nil for every other bluebook.
         namespace:         :namespace,
         aggregates:        many(:aggregates),
         read_models:       many(:read_models),
@@ -36,17 +36,20 @@ module Hecks
         # One row per declared `provides` capability, in declaration order;
         # present (possibly empty) like `attaches_to`.
         provides:          -> { provides.map(&:to_h) },
+        # One row per aggregate a module groups, in declaration order; left out when the bluebook
+        # declares no module, so a bluebook that never groups emits as it did.
+        modules:           -> { modules.empty? ? Hecks::IR::OMIT : modules.map(&:to_h) },
         canonical_form:    -> { Expression::CanonicalForm.table }
       )
 
-      # One row of a declared capability — `verb` is chapter-local;
-      # `Behaviour::Chapter#provided_verb` qualifies it with the chapter's own name.
+      # One row of a declared capability — `verb` is bluebook-local;
+      # `Behaviour::Bluebook#provided_verb` qualifies it with the bluebook's own name.
       Provision = Struct.new(:capability, :key, :verb, keyword_init: true) do
         # Coerces one declared or reconstructed `provides` row into a `Provision`.
         #
-        # @param row [Bluebook::Chapter::Provision, #to_h] a `Provision` already, or
+        # @param row [Bluebook::Declaration::Provision, #to_h] a `Provision` already, or
         #   anything answering `to_h` with `capability`/`key`/`verb` entries
-        # @return [Bluebook::Chapter::Provision] `row` itself if it already is one, else
+        # @return [Bluebook::Declaration::Provision] `row` itself if it already is one, else
         #   a new `Provision` built from its fields
         def self.from(row)
           return row if row.is_a?(self)
@@ -56,19 +59,37 @@ module Hecks
         end
       end
 
+      # One aggregate's membership of a module: the module's name and vision, and the aggregate.
+      ModuleRow = Struct.new(:name, :vision, :aggregate, keyword_init: true) do
+        # Coerces one declared or reconstructed module row into a `ModuleRow`.
+        #
+        # @param row [Bluebook::Declaration::ModuleRow, #to_h] a `ModuleRow` already, or anything
+        #   answering `to_h` with `name`/`vision`/`aggregate` entries
+        # @return [Bluebook::Declaration::ModuleRow] `row` itself if it already is one, else a new one
+        def self.from(row)
+          return row if row.is_a?(self)
+
+          fields = row.to_h.transform_keys(&:to_sym)
+          new(name: fields[:name].to_s, vision: fields[:vision].to_s, aggregate: fields[:aggregate].to_s)
+        end
+      end
+
+      attr_accessor :formerly_known_as
+
       attr_reader :name, :version, :vision, :aggregates, :policies, :process_managers,
-                  :classification, :read_models, :ports, :formerly_known_as, :namespace, :attaches_to, :provides
+                  :classification, :read_models, :ports, :namespace, :attaches_to, :provides,
+                  :modules
 
       # Every optional field and what it holds when the declaration omits it.
       FIELD_DEFAULTS = {
         version: nil, vision: nil, aggregates: [], policies: [], process_managers: [],
         classification: nil, read_models: [], formerly_known_as: nil, namespace: nil,
-        attaches_to: [], provides: []
+        attaches_to: [], provides: [], modules: []
       }.freeze
 
       # @param policies [Array<Bluebook::Policy>] every reaction declared across the
-      #   chapter's own aggregates, hoisted here
-      # @param classification [String, Symbol, nil] whether this chapter is central to
+      #   bluebook's own aggregates, hoisted here
+      # @param classification [String, Symbol, nil] whether this bluebook is central to
       #   its project's own domain model, or `nil` if undeclared
       def initialize(name:, **given)
         KeywordFields.assign(self, KeywordFields.fill(given, FIELD_DEFAULTS))
@@ -85,10 +106,17 @@ module Hecks
         @classification    = @classification&.to_s
         @formerly_known_as = @formerly_known_as&.to_s
         @namespace         = @namespace&.to_s
-        @attaches_to       = Array(@attaches_to).map(&:to_s)
-        @provides          = Array(@provides).map { |row| Provision.from(row) }
+        coerce_rows
       end
       private :coerce_fields
+
+      # Holds every row-valued field as the rows its reader answers.
+      def coerce_rows
+        @attaches_to = Array(@attaches_to).map(&:to_s)
+        @provides    = Array(@provides).map { |row| Provision.from(row) }
+        @modules     = Array(@modules).map { |row| ModuleRow.from(row) }
+      end
+      private :coerce_rows
     end
   end
 end

data/lib/hecks/bluebook/domain_port.rb

@@ -10,9 +10,12 @@ module Hecks
       include Hecks::IR
       include Behaviour::PortOperation
 
-      emits_ir(name: :hecks_name, attributes: many(:attributes), emits: :emits)
+      emits_ir(
+        name: :hecks_name, attributes: many(:attributes), emits: :emits,
+        handles: -> { handles.map { |held| { command: held[:command], value: held[:value] } } }
+      )
 
-      attr_reader :hecks_name, :attributes, :emits, :direction, :answers, :refuses, :to
+      attr_reader :hecks_name, :attributes, :emits, :direction, :answers, :refuses, :to, :handles
 
       # Marks this operation as the one the hecksagon picks (`ask_via`) when its ask name is
       # declared on more than one port of the aggregate.
@@ -29,7 +32,8 @@ module Hecks
       #
       # Every optional keyword and what it holds when the declaration omits it.
       FIELD_DEFAULTS = {
-        attributes: [], emits: [], direction: :inbound, answers: nil, refuses: nil, to: nil, chosen: false
+        attributes: [], emits: [], direction: :inbound, answers: nil, refuses: nil, to: nil, chosen: false,
+        handles: []
       }.freeze
 
       # @param name [String, Symbol] the operation's declared name

data/lib/hecks/bluebook/dsl/adapter_builder.rb

@@ -14,11 +14,16 @@ module Hecks
         include WordGate
 
         # @param name [String] the adapter's name, as written after `Hecks.adapter`
-        def initialize(name)
+        # @param source_dir [String, nil] the directory of the `.adapter` file, which a plugin's
+        #   `runs` path is read against
+        def initialize(name, source_dir: nil)
           @name = name
+          @source_dir = source_dir
           @fields   = []
           @secrets  = []
           @defaults = {}
+          @answers  = []
+          @provides = []
         end
 
         # Names the port this adapter implements; a repeated call replaces the earlier name.
@@ -44,14 +49,33 @@ module Hecks
         # @return [Array<Symbol>] every secret declared so far, this one last
         def secret(name) = @secrets << name.to_sym
 
-        # Assembles the collected port, fields, defaults and secrets, judged by the adapter
+        # Names one query this adapter answers, qualified by its bluebook and aggregate.
+        #
+        # @param name [String] the query, such as `"Calendar::Event.Occurrences"`
+        # @return [Array<String>] every query named so far, this one last
+        def answers_query(name) = @answers << name.to_s
+
+        # Names one capability this adapter provides beyond its port's contract.
+        #
+        # @param capability [String, Symbol] the capability, such as `"set_transform"`
+        # @return [Array<String>] every capability named so far, this one last
+        def provides(capability) = @provides << capability.to_s
+
+        # Names the wasm module this adapter runs, beside its `.adapter` file.
+        #
+        # @param file [String] the module's file name, such as `"occurrences.wasm"`
+        # @return [String] the file name as stored
+        def runs(file) = @runs = file.to_s
+
+        # Assembles the collected port, fields, defaults, secrets and plugin, judged by the adapter
         # language.
         #
         # @return [Bluebook::Adapter] the adapter, returned once the language accepts it
         # @raise [Bluebook::DSL::Malformed] if the adapter language refuses the declaration
         def build
           MetaValidator.call_adapter(
-            Adapter.new(name: @name, port: @port, fields: @fields, secrets: @secrets, defaults: @defaults)
+            Adapter.new(name: @name, port: @port, fields: @fields, secrets: @secrets, defaults: @defaults,
+                        answers: @answers, runs: @runs, provides: @provides, source_dir: @source_dir)
           )
         end
 
@@ -63,7 +87,7 @@ module Hecks
         # @raise [Bluebook::DSL::Malformed] if the adapter language refuses the declaration, or
         #   the block uses a word the `Adapter` grammar does not admit
         def self.build(name, &block)
-          builder = new(name)
+          builder = new(name, source_dir: block && File.dirname(block.source_location.first))
           builder.instance_eval(&block) if block
           builder.build
         end

data/lib/hecks/bluebook/dsl/aggregate_builder/draining.rb

@@ -58,8 +58,8 @@ module Hecks
                                     identity_name_prefix:            "#{Naming.demodulise(@name)}#{Naming.demodulise(name)}",
                                     identity_value_object_installer: ->(value_object) { @value_objects << value_object },
                                     aggregate_name:                  @name,
-                                    chapter_entity_named_givens:     @chapter_entity_named_givens,
-                                    chapter_entity_pending_givens:   @chapter_entity_pending_givens,
+                                    bluebook_entity_named_givens:    @bluebook_entity_named_givens,
+                                    bluebook_entity_pending_givens:  @bluebook_entity_pending_givens,
                               &block)
         end