hecks 1.3.0 → 1.5.0

data/lib/hecks/bluebook/assembly/specializer.rb

@@ -1,50 +1,49 @@
 module Hecks
   module Bluebook
     class Assembly
-      # THE FIRST SPECIALIZER — a projection of `contracts.rb`'s `fields:` table,
+      # **The first specializer** — a projection of `contracts.rb`'s `fields:` table,
       # derived from the language's own description of a category instead of
       # hand-written beside it.
       #
       # `Plan` already reads `grammar_registry` to build the judge's walk ; this
-      # reads the same chapter to build the OTHER table this arc's own header
-      # names as duplication — "SPELLED AS THE IR SPELLS THEM," field for field,
+      # reads the same chapter to build the other table this arc's own header
+      # names as duplication — "spelled as the IR spells them," field for field,
       # for every category simple enough to say so.
       #
-      # ONE CASE, PROVEN, NOT THE WHOLE TABLE. A field this can speak for is
+      # One case, proven, not the whole table. A field this can speak for is
       # scalar and not a reference — every other field (a list, a reference, a
       # fold like Lifecycle) is exactly what `contracts.rb`'s `reads:`/`derived:`
       # exist to say, and stays hand-written until a later projection learns to
       # derive readers and folds too. Restricting the claim to what can be
-      # PROVEN CORRECT — checked in spec/specializer_spec.rb against two
+      # proven correct — checked in spec/specializer_spec.rb against two
       # independent categories — is the same discipline `derived:` itself
       # enforces : a claim needs a kind, and this one's kind is "plain, checked."
       module Specializer
         module_function
 
-        # `position` IS THE FIRST FOLD THIS RUNS INTO, and it is a universal
-        # one : every category declares `attribute :position, Position` — for
-        # the JUDGE's own walk, `order_by :position` on its `DeclaredIn` ask —
-        # but no `*` constructor takes it as an argument. `contracts.rb`
-        # already says so, in the language every other derived field speaks :
-        # `derived: { position: :walk }`. The language says a category HAS a
-        # position ; it does not say a category's OWN constructor is handed
-        # one, and that second fact is exactly what `fields:` needs to answer.
-        # So this is not silently special-cased — it is the one fold named
-        # here because it is the one fold that is not a lucky accident of
-        # Policy or Handler, but a fact true of every category this arc will
-        # ever reach.
-        DERIVED_EVERYWHERE = %i[position].freeze
-
         # S17, ADR 0026 — `Handler` is a genuine entity now, nested under
         # `ProcessManager`, so `.aggregate` alone no longer finds it —
         # it hangs off some aggregate's own `.entities` instead
         # (searched recursively, the same reason `Value::Coercion#find_
-        # entity` does: a NESTED entity, like `Dispatch` inside
+        # entity` does: a nested entity, like `Dispatch` inside
         # `Handler`, is not a direct child of any aggregate either).
+        #
+        # @param chapter [Bluebook::Chapter] the chapter to search
+        # @param name [String, Symbol] the construct's declared name
+        # @return [Bluebook::Aggregate, Class, nil] the aggregate, or the entity class
+        #   (a `Bluebook::Entity` subclass) nested anywhere under one, or `nil` if
+        #   `chapter` declares no construct by that name
         def construct_for(chapter, name)
           chapter.aggregate(name) || chapter.aggregates.filter_map { |a| find_entity(a, name) }.first
         end
 
+        # Searches a construct's own entities, recursively, for one by name.
+        #
+        # @param construct [Bluebook::Aggregate, Class] the aggregate, or entity class,
+        #   to search under
+        # @param name [String, Symbol] the entity's declared name
+        # @return [Class, nil] the entity class (a `Bluebook::Entity` subclass), or `nil`
+        #   if none of `construct`'s nested entities has that name
         def find_entity(construct, name)
           construct.entities.each do |candidate|
             return candidate if candidate.hecks_name == name
@@ -55,11 +54,29 @@ module Hecks
           nil
         end
 
+        # `position` is the first fold this runs into : a category declares
+        # `attribute :position, Position` — for the judge's own walk,
+        # `order_by :position` on its `DeclaredIn` ask — but no `*`
+        # constructor takes it as an argument. `contracts.rb` already says so,
+        # in the language every other derived field speaks :
+        # `derived: { position: :walk }`. The language says a category has a
+        # position ; it does not say a category's own constructor is handed
+        # one, and that second fact is exactly what `fields:` needs to answer.
+        # So the skip reads the category's own walk claims (`Contract#walked`)
+        # rather than restating `position` here — Handler, which has no
+        # walk-minted position, skips nothing.
+        #
+        # @param category [String, Symbol] the construct category's name, such as
+        #   `"Aggregate"` or `"Command"`
+        # @return [Hash{Symbol => Array(Symbol, Symbol)}] a `contracts.rb`-shaped
+        #   `fields:` table, one `field => [field, :plain]` entry per scalar,
+        #   non-reference, non-walked attribute the language declares for `category`
         def fields_for(category)
           language = construct_for(MetaValidator.grammar_registry.bluebook("Bluebook"), category.to_s)
+          walked   = Assembly.contract(category).walked
           language.attributes.each_with_object({}) do |attribute, fields|
             next if attribute.list? || attribute.reference?
-            next if DERIVED_EVERYWHERE.include?(attribute.name)
+            next if walked.include?(attribute.name)
 
             fields[attribute.name] = [attribute.name, :plain]
           end

data/lib/hecks/bluebook/assembly.rb

@@ -1,6 +1,6 @@
 module Hecks
   module Bluebook
-    # A GRAPH BUILT FROM DECLARATIONS, rather than from DSL calls.
+    # A graph built from declarations, rather than from DSL calls.
     #
     # This is the half that lets the language orchestrate. `Reconstruction` reads a
     # chapter back out of the meta-domain, in declaration order, as plain
@@ -8,32 +8,50 @@ module Hecks
     # into the graph the runtime runs: IR aggregates with their verbs, value
     # objects, entities and asks, owned by the chapter that declares them.
     #
-    # It takes a HASH, not a runtime, on purpose. That makes it a pure inverse of
+    # ## Why a hash, not a runtime
+    #
+    # It takes a hash, not a runtime, on purpose. That makes it a pure inverse of
     # `to_h` and testable without the meta-domain in the picture at all:
     #
     #     Assembly.call(built.to_h).to_h == built.to_h
     #
     # which is the check `spec/assembly_spec` makes for every chapter in the tree.
     # Feed it the reconstruction instead and the same code assembles what the
-    # LANGUAGE holds — the only difference being where the declarations came from.
+    # language holds — the only difference being where the declarations came from.
+    #
+    # ## One table, not a method per category
     #
-    # EVERY FIELD IS READ FROM ONE TABLE. There is no method per category here:
+    # Every field is read from one table. There is no method per category here:
     # `Contracts` names what the language cannot say about a construct, `Build`
-    # reads it, and the coverage gate holds the table to the language. The first
-    # draft of this file did have a method each, which is the shape the judge used
-    # to have — and the price of that shape was fourteen verbs the language declared
-    # and nothing ever offered.
+    # reads it, and the coverage gate holds the table to the language. A method
+    # per category can decorate a verb the language declares without ever
+    # offering it; the table cannot, because `spec/assembly_spec` checks every
+    # field the language declares against it.
+    #
+    # ## What stays hand-written
     #
-    # What stays hand-written is the CONTAINMENT: which construct holds which.
-    # That is not a field table. (The runtime SURFACE is no longer built here at
-    # all — the door is a per-boot projection, facade/surface.rb.)
+    # The containment — which construct holds which — stays hand-written; it is
+    # not a field table. The runtime surface is no longer built here at all — the
+    # door is a per-boot projection, facade/surface.rb.
     class Assembly
+      # Builds the graph the runtime runs from one chapter's declared hash.
+      #
+      # @param declaration [Hash{Symbol => Object}] a chapter's declarations, in the
+      #   shape `Chapter#to_h` spells
+      # @return [Bluebook::Chapter] the assembled chapter, with its aggregates, read
+      #   models and process managers built and wired
       def self.call(declaration) = new(declaration).bluebook
 
+      # @param declaration [Hash{Symbol => Object}] a chapter's declarations, in the
+      #   shape `Chapter#to_h` spells
       def initialize(declaration)
         @declaration = declaration
       end
 
+      # Assembles this instance's declared hash into the chapter's runtime graph.
+      #
+      # @return [Bluebook::Chapter] the assembled chapter, with its aggregates, read
+      #   models and process managers built and wired
       def bluebook
         aggregates = Array(@declaration[:aggregates]).map { |row| AggregateAssembly.new(row).aggregate }
         models     = Array(@declaration[:read_models]).map { |row| Build.call("ReadModel", row) }
@@ -50,7 +68,7 @@ module Hecks
       private
 
       # Every reaction the chapter holds, and each one also handed back to the head
-      # that declared it — the builder keeps a policy in BOTH places, hoisting it onto
+      # that declared it — the builder keeps a policy in both places, hoisting it onto
       # the chapter where the runtime reads it while the head keeps its own list. The
       # language records which head, so the assembly can put it back.
       def reactions(aggregates)
@@ -72,10 +90,10 @@ module Hecks
                    dispatches: Array(row[:dispatches]).map { |leg| dispatch(leg) })
       end
 
-      # `compensates` — a PLAIN HASH on the declaration (`Reconstruction#
+      # `compensates` — a plain hash on the declaration (`Reconstruction#
       # dispatch`'s own comment for why), built into the real
       # `DispatchSpec` its own field actually is by recursing through
-      # THIS SAME method, one level in — the identical move `handler`
+      # this same method, one level in — the identical move `handler`
       # itself takes into `dispatches`, one level up. `nil` when there
       # is nothing to compensate; `Build.call` never sees a
       # `compensates:` key it does not know how to read either way, the

data/lib/hecks/bluebook/attribute.rb

@@ -28,15 +28,15 @@ module Hecks
 
       attr_reader :name, :type, :default, :pattern, :admits, :relationship
 
-      # A Reference is kept AS ITSELF. Every other type is still a name, and
+      # A Reference is kept as itself. Every other type is still a name, and
       # crosses over as its construct does.
       #
-      # `admits` names an ALREADY-DECLARED closed set the value must belong
+      # `admits` names an already-declared closed set the value must belong
       # to — `Vocabulary::QueryComparator` — spelled aggregate-qualified
-      # because the set is a value object INSIDE an aggregate, and the
+      # because the set is a value object inside an aggregate, and the
       # aggregate is the only thing `reference_to` can reach.
       #
-      # ON THE WIRE, because it is a RULE and not only a typing hint.
+      # On the wire, because it is a rule and not only a typing hint.
       #
       # It began as neither. The link existed so a generator could type
       # `WhereClause.op` as `WhereOp` — a typing convenience, not worth
@@ -48,9 +48,24 @@ module Hecks
       # refused "burnt" through one reading and emitted the event through
       # another.
       #
-      # The wire carries the NAME, not the members. A reader resolves it
+      # The wire carries the name, not the members. A reader resolves it
       # against the IR it holds, so the members are declared once and
       # copied nowhere — which is the same reason `admits` exists at all.
+      #
+      # @param name [Symbol, String] the attribute's name
+      # @param type [Module, Bluebook::Reference, String, Symbol] the bare constant naming
+      #   a primitive or a value object, a `reference_to`-built Reference, or already-spelled
+      #   text
+      # @param list [Boolean] whether this attribute holds a list of values rather than one
+      # @param default [Object, nil] the value a new record starts with when none is given
+      # @param optional [Boolean] whether a command may omit this attribute
+      # @param pattern [String, nil] a regex source the value must match; shared-engine
+      #   subset only (`PatternSubset`)
+      # @param admits [String, nil] an already-declared closed set's aggregate-qualified
+      #   name, such as `"Vocabulary::QueryComparator"`, that the value must belong to
+      # @param relationship [Symbol, nil] the DSL word that minted this attribute
+      #   (`:reference_to`, `:has_many`, `:has_one` or `:belongs_to`), or `nil` for an
+      #   ordinary attribute
       def initialize(name:, type:, list: false, default: nil, optional: false, pattern: nil,
                      admits: nil, relationship: nil)
         @name     = name.to_sym
@@ -63,13 +78,13 @@ module Hecks
         @relationship = relationship&.to_s
       end
 
-      # A BARE CONSTANT IN A BLUEBOOK IS A NAME, EVEN WHEN RUBY HAS HEARD OF IT.
+      # A bare constant in a bluebook is a name, even when Ruby has heard of it.
       #
       # `BluebookBuilder.build` says exactly this and installs a `const_missing`
       # resolver that hands back the symbol — `attribute :target, Target` becomes
       # the name "Target" and nothing looks Target up. That works only while the
-      # lookup FAILS, and `Facade::Surface` installs every aggregate name as a
-      # TOP-LEVEL constant (its own comment, and `ConstShim`'s, both say so).
+      # lookup fails, and `Facade::Surface` installs every aggregate name as a
+      # top-level constant (its own comment, and `ConstShim`'s, both say so).
       #
       # So in one process: boot a domain with an aggregate named `Target`, then
       # load a chapter whose own value object is called `Target`, and Ruby
@@ -77,11 +92,11 @@ module Hecks
       # built against somebody else's aggregate — silently, with no refusal —
       # and the attribute stops meaning what the file plainly says.
       #
-      # DEMODULISED, so both paths spell it the same: `:Target` and
+      # Demodulised, so both paths spell it the same: `:Target` and
       # `QualityControl::Target` are both "Target". A plain class stays itself —
       # `String` demodulises to "String" — so the ordinary case is untouched.
       # This does not undo the constant leak; it makes the leak unable to change
-      # what a chapter MEANS, which is the part that has to hold.
+      # what a chapter means, which is the part that has to hold.
       def spell(type)
         return type if type.is_a?(Reference)
         return Naming.demodulise(type) if type.is_a?(Module)
@@ -91,8 +106,7 @@ module Hecks
       private :spell
 
       # Held because a declared vocabulary pins it — spec/vocabulary_conformance
-      # holds `Primitive`'s members to this list. The `primitive?` predicate that
-      # used to read it had no caller anywhere and is gone.
+      # holds `Primitive`'s members to this list.
       PRIMITIVES = Hecks::Vocabulary.fetch("Primitive")
 
       # `type` is spelled, never handed over. A Reference renders as

data/lib/hecks/bluebook/behaviour/aggregate.rb

@@ -3,14 +3,14 @@ require_relative "traits"
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT AN AGGREGATE DOES, as opposed to what it holds.
+      # What an aggregate does, as opposed to what it holds.
       #
       # The holding half — the field list, the readers, the emission — is
       # the same list the language already declares in
       # `language/bluebook/aggregate.bluebook`, said a second and third
       # time in Ruby. This half is not: derived identity, the name
       # indexes, the owner stamping and the finders are decisions about
-      # HOW the declared shape is used, and no grammar states them.
+      # how the declared shape is used, and no grammar states them.
       #
       # Split so the holding half can be generated from the language
       # without any of this being in the blast radius of a regeneration.
@@ -24,13 +24,19 @@ module Hecks
         include Indexed
         include Owns
 
-        # An aggregate is a MEMBER of its chapter's namespace — "Pizzas::Pizza" —
-        # where everything else is declared ON its owner and joins with ".".
+        # An aggregate is a member of its chapter's namespace — "Pizzas::Pizza" —
+        # where everything else is declared on its owner and joins with ".".
+        #
+        # @return [String] the literal string `"::"`
         def hecks_separator = "::"
 
-        # THE HOOK THE GENERATED CONSTRUCTOR CALLS once every declared
+        # The hook the generated constructor calls once every declared
         # field is assigned. Nothing here is derivable from the
         # declaration, which is exactly why it is not generated.
+        #
+        # @return [Bluebook::Aggregate] self, once identity is derived, every
+        #   declaration is indexed and its commands, value objects, entities and
+        #   queries are stamped as owned by it
         def settle
           derive_identity
           index_declarations
@@ -40,42 +46,68 @@ module Hecks
           self
         end
 
+        # Builds every by-name finder index `settle` needs — attributes, value
+        # objects, commands, queries, ports and projected fields.
+        #
+        # @return [void]
         def index_declarations
           index_attributes(@attributes)
           @value_objects_by_name = index_by_hecks_name(@value_objects)
           @commands_by_name      = index_by_hecks_name(@commands)
           @queries_by_name       = index_by_hecks_name(@queries)
           @ports_by_name         = @ports.to_h { |port| [port.name, port] }
-          # S12, ADR 0025 — keyed by SYMBOL, the same convention
+          # S12, ADR 0025 — keyed by symbol, the same convention
           # `Indexed#attribute` already uses; `GuardState` asks for one
           # by name at every dispatch, the rebuild sweep walks all of
           # them once per pass.
           @projected_fields_by_name = @projected_fields.to_h { |field| [field.name, field] }
         end
 
+        # Finds a declared `projects` field by its declared name.
+        #
+        # @param named [String, Symbol] the projected field's declared name
+        # @return [Bluebook::ProjectedField, nil] the field named `named`, or
+        #   `nil` if none is declared under that name
         def projected_field(named) = @projected_fields_by_name[named.to_sym]
 
-        # A value object is a CLASS now, so `name` is Ruby's answer (the constant
+        # A value object is a class now, so `name` is Ruby's answer (the constant
         # path) and the declared name is `hecks_name`. This finder is on its way
-        # out — once an attribute's type IS the class there is nothing to find —
+        # out — once an attribute's type is the class there is nothing to find —
         # but every consumer still asks by type string, so it stays until they
         # stop.
+        #
+        # @param named [String, Symbol] the value object's declared name
+        # @return [Class, nil] the value object class (a `Bluebook::ValueObject`
+        #   subclass) named `named`, or `nil` if none is declared under that name
         def value_object(named) = @value_objects_by_name[named.to_s]
+
+        # Finds a port attached to this aggregate by its declared name.
+        #
+        # @param named [String, Symbol] the port's declared name
+        # @return [Bluebook::DomainPort, nil] the port named `named`, or `nil` if
+        #   none is attached under that name
         def port(named)         = @ports_by_name[named.to_s]
 
-        # A PORT IS DECLARED IN THE HECKSAGON, NOT THE BLUEBOOK — the
+        # A port is declared in the hecksagon, not the bluebook — the
         # boundary between the domain and its adapters, in hexagonal terms,
-        # is exactly what a `.hecksagon` file already IS for every other
-        # port (persistence, projection, ...). So this attaches AFTER the
+        # is exactly what a `.hecksagon` file already is for every other
+        # port (persistence, projection, ...). So this attaches after the
         # aggregate already exists and is registered — `HecksagonBuilder`
         # calls it once per `port` declaration, having already stamped each
         # operation's reference attributes with `declared_in = self`, since
         # nothing upstream of a hecksagon load does that for it.
+        #
+        # @param port [Bluebook::DomainPort] the aggregate-scoped port to attach
+        # @return [void]
         def add_port(port)
           @ports << port
           @ports_by_name[port.name] = port
         end
 
+        # Names the table, file or key persistence adapters store this aggregate
+        # under.
+        #
+        # @return [String] the aggregate's name, snake-cased
         def storage_name = Naming.snake(@name)
       end
     end

data/lib/hecks/bluebook/behaviour/attribute.rb

@@ -1,25 +1,38 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT AN ATTRIBUTE DOES. The declared half — name, type, list,
+      # **What an attribute does**. The declared half — name, type, list,
       # default, optional, pattern, admits — is what the language states
       # in `aggregate.bluebook`'s own `Field`. These are the questions
-      # readers ask ABOUT that shape, which no declaration states.
+      # readers ask about that shape, which no declaration states.
       module Attribute
+        # Says whether this attribute was declared `list`.
+        #
+        # @return [Boolean] whether this attribute holds a list of values rather than one
         def list?      = @list
+
+        # Says whether this attribute holds a single value rather than a list.
+        #
+        # @return [Boolean] whether this attribute holds a single value rather than a list
         def scalar?    = !@list
+
+        # Says whether this attribute's type is another aggregate reached via `reference_to`.
+        #
+        # @return [Boolean] whether this attribute's type is a `reference_to` another aggregate
         def reference? = @type.is_a?(Reference)
 
-        # MAY THIS FACT BE LEFT OUT?
+        # May this fact be left out?
         #
         # Required is the default and by far the common case — a command takes
-        # the arguments it declares, and all of them — so the EXCEPTION is what
+        # the arguments it declares, and all of them — so the exception is what
         # gets marked. Marking the other way would annotate almost every
         # attribute in the corpus to say nothing.
         #
-        # Only a COMMAND enforces this. An aggregate's own attributes are filled
+        # Only a command enforces this. An aggregate's own attributes are filled
         # by the commands that set them, and a value object's by its
         # constructor ; neither is a payload anyone hands in.
+        #
+        # @return [Boolean] whether a command may omit this attribute from its payload
         def optional? = @optional
       end
     end

data/lib/hecks/bluebook/behaviour/chapter.rb

@@ -3,19 +3,22 @@ require_relative "traits"
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT A CHAPTER DOES. The declared half is the roll-call of what a
+      # **What a chapter does**. The declared half is the roll-call of what a
       # bluebook holds; these are the finders over it, plus `verbs` — the
       # chapter's own list of every dispatchable name, which is derived
       # from the aggregates rather than declared anywhere.
       module Chapter
         include Owns
 
-        # THE HOOK THE GENERATED CONSTRUCTOR CALLS. Three things a
-        # declaration does not state: that a chapter is the ROOT of the
+        # The hook the generated constructor calls. Three things a
+        # declaration does not state: that a chapter is the root of the
         # owner chain (nothing declares it, it is what having no owner
-        # MEANS), the ports table — which a `.hecksagon` fills later, so
+        # means), the ports table — which a `.hecksagon` fills later, so
         # the bluebook cannot declare it — and stamping its own children,
         # the same act an Aggregate performs one level down.
+        #
+        # @return [Bluebook::Chapter] self, once root marking, the ports table and ownership
+        #   stamping are all set up
         def settle
           @hecks_root    = true
           @ports         = []
@@ -24,18 +27,83 @@ module Hecks
           self
         end
 
+        # Finds a declared aggregate by name.
+        #
+        # @param named [String, Symbol] the aggregate's declared name
+        # @return [Bluebook::Aggregate, nil] the aggregate, or `nil` if none is declared
+        #   by that name
         def aggregate(named)  = @aggregates.find { |a| a.name == named.to_s }
+
+        # Finds a declared read model by its own name or by the query name it answers.
+        #
+        # @param named [String, Symbol] the read model's declared name, or its query name
+        # @return [Bluebook::ReadModel, nil] the read model, or `nil` if none matches
         def read_model(named) = @read_models.find { |model| model.name == named.to_s || model.query_name == named.to_s }
+
+        # Finds a port declared at this chapter's root by name.
+        #
+        # @param named [String, Symbol] the port's declared name
+        # @return [Bluebook::DomainPort, nil] the port, or `nil` if none is declared
+        #   by that name
         def port(named)       = @ports_by_name[named.to_s]
 
-        # A PORT IS DECLARED IN THE HECKSAGON, not the bluebook — so it
+        # What this chapter declared it provides — `{ key => local verb }`
+        # for one capability, or nil when it declares none. Read by
+        # everything that resolves a capability's provider from what a
+        # chapter declares, rather than from the chapter's own name
+        # (`Registry#authorization_provider_for`).
+        #
+        # @param capability [String, Symbol] the capability's name, such as
+        #   `Bluebook::Capabilities::AUTHORIZATION`
+        # @return [Hash{Symbol => String}, nil] each declared key mapped to its local verb,
+        #   or `nil` if this chapter declares no `provides` row for that capability
+        def provision(capability)
+          rows = @provides.select { |row| row.capability == capability.to_s }
+          rows.empty? ? nil : rows.to_h { |row| [row.key.to_sym, row.verb] }
+        end
+
+        # Says whether this chapter declares that it provides a capability.
+        #
+        # @param capability [String, Symbol] the capability's name
+        # @return [Boolean] whether this chapter declares a `provides` row for that capability
+        def provides?(capability) = !provision(capability).nil?
+
+        # The declared verb for `key`, qualified with this chapter's own
+        # name — the spelling `Dispatcher#dispatch`/`#query` take.
+        #
+        # @param capability [String, Symbol] the capability's name
+        # @param key [String, Symbol] the provided key to resolve
+        # @return [String, nil] the verb qualified as `"ChapterName::verb"`, or `nil` if this
+        #   chapter provides no such capability or key
+        def provided_verb(capability, key)
+          local = provision(capability)&.fetch(key.to_sym, nil)
+          local && "#{name}::#{local}"
+        end
+
+        # A port is declared in the hecksagon, not the bluebook — so it
         # attaches after the chapter already exists, the same way an
         # aggregate's own ports do.
+        #
+        # @param port [Bluebook::DomainPort] the operations-shaped port to attach
+        # @return [void]
         def add_port(port)
           @ports << port
           @ports_by_name[port.name] = port
         end
 
+        # A TRANSLATED REACTION IS ALSO DECLARED IN THE HECKSAGON —
+        # `HecksagonBuilder#translates` builds an ordinary `Policy` (same
+        # shape, same `PolicyInterpreter` runtime, as one written inside a
+        # `policy` block in this chapter's own `.bluebook`) and attaches it
+        # here, after the chapter already exists, the same reasoning
+        # `add_port` gives one method up. Kept out of the bluebook itself
+        # on purpose: which FOREIGN domain's event this chapter reacts to
+        # is a wiring/context-mapping decision, not a fact the domain
+        # states about its own model.
+        def add_policy(policy)
+          @policies << policy
+        end
+
         # Every dispatchable name this chapter answers to, spelled exactly
         # as Dispatcher#dispatch takes it. Derived from the aggregates,
         # never declared — which is why Projections::OIDC can hold its own
@@ -50,6 +118,9 @@ module Hecks
         # already proved out for the meta-domain's own grammar (S17, ADR
         # 0026) — entities nest arbitrarily deep (`Dispatch`, inside
         # `Handler`), so one flat level isn't enough.
+        #
+        # @return [Array<String>] every command verb reachable on this chapter, spelled
+        #   `"Domain::Aggregate.command"` or, nested, `"Domain::Aggregate.Entity.command"`
         def verbs
           @aggregates.flat_map { |agg| aggregate_verbs(agg) }
         end