hecks 1.3.0 → 1.5.0

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

@@ -1,8 +1,13 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT A QUERY DOES beyond holding its declared shape.
+      # What a query does beyond holding its declared shape.
       module Query
+        # Finds a declared result attribute by name.
+        #
+        # @param named [String, Symbol] the attribute's declared name
+        # @return [Bluebook::Attribute, nil] the attribute, or `nil` if none is declared
+        #   by that name
         def attribute(named) = @attributes.find { |a| a.name == named.to_sym }
       end
     end

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

@@ -1,27 +1,38 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT A READ MODEL DOES. Its declared half is the gathered heads
+      # **What a read model does**. Its declared half is the gathered heads
       # and the query shape; these are readings taken off them.
       module ReadModel
+        # Lists the fields this read model groups rows by.
+        #
+        # @return [Array<Symbol>] each declared `group_by` field's name, in declaration order
         def group_by_fields = @group_by.map { |row| row[:field].to_sym }
 
         # `!!` rather than a bare `@count` — the DSL/reconstruction
         # boundary (ReadModel#initialize) already normalises to
         # `true`/`nil`, so this is belt and braces against a future
         # caller constructing a ReadModel by hand with `count: false`.
+        #
+        # @return [Boolean] whether this read model reduces to a row count
         def count? = !!@count
 
+        # Names the verb `Dispatcher#query` looks this read model up by.
+        #
+        # @return [String] this read model's name in `snake_case`
         def query_name = Naming.snake(@name)
 
-        # WHICH GATHERED HEADS THE FILTERING APPLIES TO (ADR 0055) — plural,
+        # Which gathered heads the filtering applies to (ADR 0055) — plural,
         # since `where`/`order_by`/`limit`/`offset` can now each independently
         # name a many-side head via `on:` once there's more than one. A read
         # model with a single many-side head keeps the old reading: every
-        # UNTARGETED option (plus `group_by`/`count`/`median`, still
+        # untargeted option (plus `group_by`/`count`/`median`, still
         # single-head-only — ADR 0055) applies to it, same as before `on:`
         # existed. With several many-side heads, only the ones actually named
         # by a targeted option are eligible.
+        #
+        # @return [Array<Symbol>] the `:as` name of each many-side head that filtering
+        #   applies to; `[]` if this read model has no many-side head
         def filtered_head_names
           many = @aggregate_heads.select { |head| head[:many] }
           return [] if many.empty?
@@ -33,26 +44,36 @@ module Hecks
         end
 
         # The pre-`on:` reading (ADR 0055), unchanged: with exactly one
-        # many-side head, every UNTARGETED option (plus `group_by`/`count`/
+        # many-side head, every untargeted option (plus `group_by`/`count`/
         # `median`, still single-head-only) applies to it — split out only
         # to keep `filtered_head_names` itself under this file's own
         # complexity budget, not because the two questions differ in kind.
+        #
+        # @param many [Array<Hash{Symbol => Object}>] the read model's many-side
+        #   `aggregate_heads` rows; must hold exactly one
+        # @return [Array<Symbol>] `[the one head's :as name]` if any filtering option is
+        #   declared, else `[]`
         def single_filtered_head_name(many)
           declared = wheres.any? || order_by || limit || offset || authorization&.tenant ||
                      @group_by.any? || count? || @median_field
           declared ? [many.first[:as]] : []
         end
 
-        # THE where/order_by/limit/offset THAT APPLY TO ONE ELIGIBLE HEAD
+        # The where/order_by/limit/offset that apply to one eligible head
         # (ADR 0055) — a small view `Ports::Query::InMemory.execute` reads
         # exactly the way it already reads a whole `Query`/`ReadModel`
         # (`.wheres`/`.order_by`/`.limit`/`.offset`/`.null_semantics`), scoped
-        # to `head_as`'s own aggregate: an UNTARGETED option applies when
-        # `head_as` is the read model's ONE many-side head (the pre-`on:`
-        # reading, unchanged) ; a TARGETED one applies when its `target`
+        # to `head_as`'s own aggregate: an untargeted option applies when
+        # `head_as` is the read model's one many-side head (the pre-`on:`
+        # reading, unchanged) ; a targeted one applies when its `target`
         # resolves to `head_as`'s own aggregate.
         FilteredOptions = Struct.new(:wheres, :order_by, :limit, :offset, :null_semantics)
 
+        # Scopes this read model's filtering options down to one included head.
+        #
+        # @param head_as [Symbol] the `:as` name of the head to scope filtering to
+        # @return [FilteredOptions] the `wheres`/`order_by`/`limit`/`offset` that apply to
+        #   `head_as`, and this read model's own `null_semantics`
         def options_for(head_as)
           many = @aggregate_heads.select { |head| head[:many] }
           aggregate_name = @aggregate_heads.find { |head| head[:as] == head_as }&.fetch(:aggregate)

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

@@ -1,7 +1,7 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # THE BEHAVIOUR MORE THAN ONE CONSTRUCT SHARES.
+      # The behaviour more than one construct shares.
       #
       # None of this is new duplication. `attribute(named)` was written
       # out four separate times — on Aggregate, Entity, Command and
@@ -11,23 +11,27 @@ module Hecks
       # files reads as four methods, and the same method in four modules
       # named `Behaviour::*` reads as one repeated.
       #
-      # Written to work whether the construct is INCLUDED into (an
-      # ordinary object like Aggregate) or EXTENDED into (a class-shaped
+      # Written to work whether the construct is included into (an
+      # ordinary object like Aggregate) or extended into (a class-shaped
       # one like Command), because every one of them reads instance
       # variables and nothing else.
 
-      # A CONSTRUCT WHOSE IDENTITY IS A JOIN OF DECLARED PATHS.
+      # A construct whose identity is a join of declared paths.
       #
-      # THE PATHS, IN DECLARATION ORDER, because the identity IS their join.
+      # The paths, in declaration order, because the identity is their join.
       # "number.value" says which field carries the identity ; several paths
       # say the identity is made of several facts, which is what anything
       # named beneath another thing needs. `identity_heads` are the attributes
       # those paths start at — what every reader that looks up or coerces an
       # attribute actually wants — and `identified_by` is the single head,
-      # offered ONLY when there is one path to have a head of. A composite has
+      # offered only when there is one path to have a head of. A composite has
       # no single head, and answering with the first would be a guess ; the
       # readers that need all of them ask for `identity_heads`.
       module Identified
+        # Derives `identity_paths`, `identity_heads` and the single-head form of
+        # `identified_by` from the declared `identified_by` path(s).
+        #
+        # @return [void]
         def derive_identity
           @identity_paths = Array(@identified_by).map(&:to_s).reject(&:empty?)
           @identity_heads = @identity_paths.map { |path| path.split(".").first.to_sym }.uniq
@@ -35,7 +39,7 @@ module Hecks
         end
       end
 
-      # A CONSTRUCT THAT ANSWERS FOR ITS OWN DECLARATIONS BY NAME.
+      # A construct that answers for its own declarations by name.
       #
       # Indexed once, since the declarations are final by the time the
       # construct exists — every dispatch asks these finders by name, and a
@@ -43,35 +47,67 @@ module Hecks
       # had already settled at boot.
       #
       # `index_by_name` takes the collections to index rather than naming
-      # them, because WHICH collections a construct has is exactly the part
+      # them, because which collections a construct has is exactly the part
       # that differs: an aggregate has five, an entity three, a command one.
       module Indexed
-        # Keyed by SYMBOL — an attribute is asked for by its declared
+        # Keyed by symbol — an attribute is asked for by its declared
         # symbol name everywhere in the runtime.
+        #
+        # @param attributes [Array<Bluebook::Attribute>] the construct's declared
+        #   attributes
+        # @return [void]
         def index_attributes(attributes)
           @attributes_by_name = attributes.to_h { |held| [held.name, held] }
         end
 
-        # Keyed by STRING and by `hecks_name` — a command, query or value
+        # Keyed by string and by `hecks_name` — a command, query or value
         # object is a construct whose Ruby `name` is something else
         # entirely (a constant path, or nothing at all for an anonymous
-        # class), so the DECLARED name is the only one worth indexing.
+        # class), so the declared name is the only one worth indexing.
+        #
+        # @param collection [Array<#hecks_name>] declared constructs to index —
+        #   value objects, commands or queries, each answering `hecks_name`
+        # @return [Hash{String => Object}] the collection keyed by each member's
+        #   `hecks_name`
         def index_by_hecks_name(collection)
           collection.to_h { |held| [held.hecks_name, held] }
         end
 
+        # Finds a declared attribute by its declared name.
+        #
+        # @param named [String, Symbol] the attribute's declared name
+        # @return [Bluebook::Attribute, nil] the attribute named `named`, or `nil`
+        #   if none is declared under that name
         def attribute(named) = @attributes_by_name[named.to_sym]
+
+        # Finds a declared command by its declared name.
+        #
+        # @param named [String, Symbol] the command's declared name
+        # @return [Class, nil] the command class (a `Bluebook::Command` subclass)
+        #   named `named`, or `nil` if none is declared under that name
         def command(named)   = @commands_by_name[named.to_s]
+
+        # Finds a declared query by its declared name.
+        #
+        # @param named [String, Symbol] the query's declared name
+        # @return [Bluebook::Query, nil] the query named `named`, or `nil` if none
+        #   is declared under that name
         def query(named)     = @queries_by_name[named.to_s]
       end
 
-      # A CONSTRUCT THAT OWNS WHAT IT DECLARES.
+      # A construct that owns what it declares.
       #
       # Owner links are only ever read lazily — hecks_fqn at ask time,
       # Reference#resolve at dispatch time — so the moment the construct
       # is complete is the right stamping point: its declarations are
       # final, and nothing outside needs to remember to stamp them.
       module Owns
+        # Stamps each of `children` as owned by this construct.
+        #
+        # @param children [Array<Object>] the construct's own declared children —
+        #   arrays or bare objects, flattened before stamping — each answering
+        #   `hecks_owner=`
+        # @return [void]
         def stamp(*children)
           children.flatten.each { |child| child.hecks_owner = self }
         end

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

@@ -1,35 +1,47 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT A VALUE OBJECT DOES. EXTENDED, not included — a value object
-      # is a CLASS (`Class.new(self)`, one per declared shape), so its
+      # **What a value object does**. Extended, not included — a value object
+      # is a class (`Class.new(self)`, one per declared shape), so its
       # behaviour is singleton behaviour, and the holding half's `absorb`
       # is what a generated constructor would be.
       module ValueObject
-        # A one_of DECLARED but left empty used to be indistinguishable from no
-        # one_of at all — both are `members: []` — so the rule about it could
-        # only live in the builder. Recording the declaration lets the language
-        # judge it, the same way an empty attribute NAME survives into the IR
-        # and is judged there.
+        # Recorded as its own fact (`closed_set`), not left to be inferred from
+        # `members: []` alone — an empty `one_of` and no `one_of` at all would
+        # otherwise be indistinguishable, which would leave the rule about it
+        # only livable in the builder. Recording the declaration lets the
+        # language judge it instead, the same way an empty attribute name
+        # survives into the IR and is judged there.
+        #
+        # @return [Boolean] whether this value object declares `one_of`, even
+        #   if left empty
         def closed_set? = @closed_set
 
+        # Finds a declared attribute by its declared name.
+        #
+        # @param named [String, Symbol] the attribute's declared name
+        # @return [Bluebook::Attribute, nil] the attribute named `named`, or
+        #   `nil` if none is declared under that name
         def attribute(named) = attributes.find { |held| held.name == named.to_sym }
 
         # A single-attribute value object (EmailAddress{address},
-        # CustomerNumber{value}) is a NAME for a scalar, not a genuine
+        # CustomerNumber{value}) is a name for a scalar, not a genuine
         # group — [[feedback_name_the_scalar_field]]. `adapters/driven/
         # sql_query_builder.rb` and `fuzzing/invalid_value_generator.rb`
         # now read through this rather than inlining the check.
         #
         # `forms/field_shape.rb`'s own two `attributes.first.name` sites
         # (`closed_set_options`/`closed_set_field`) look identical but are
-        # NOT the same question — they pick a closed set's DISCRIMINANT
+        # not the same question — they pick a closed set's discriminant
         # column, and a closed set can be genuinely multi-attribute
         # (`Runtime::Value::Admission#member_matches?`'s own comment
         # names a real one: `StatementFrequency`'s `cadence`/
         # `retention_months`/`paper_fee_cents`). `sole_attribute` would
         # return `nil` for that shape and break the discriminant lookup —
         # left as `.first` on purpose, not a missed migration.
+        #
+        # @return [Bluebook::Attribute, nil] this value object's only
+        #   attribute, or `nil` when it has zero or more than one
         def sole_attribute
           attributes.first if attributes.size == 1
         end

data/lib/hecks/bluebook/capabilities.rb

@@ -0,0 +1,27 @@
+module Hecks
+  module Bluebook
+    # What a chapter may declare it provides, and what each capability
+    # must name. A chapter that `provides "authorization"` is trusted in
+    # place of a check for the literal name "Governance" — by the role
+    # check at dispatch, the ungoverned-role refusal at boot, the
+    # authorization adapter and the fuzzer — so the declaration has to be
+    # complete and point at real verbs. `BluebookBuilder::Validation
+    # #validate_provisions!` holds every `provides` to this table.
+    #
+    #   key => :command | :query   the kind of verb that key must name
+    module Capabilities
+      AUTHORIZATION = "authorization".freeze
+
+      CONTRACTS = {
+        AUTHORIZATION => {
+          # every assignment an actor holds, current or historical
+          assignments: :query,
+          # the command that grants an actor a role
+          grant:       :command,
+          # every grant of one role acting as another
+          transitions: :query
+        }.freeze
+      }.freeze
+    end
+  end
+end

data/lib/hecks/bluebook/chapter.rb

@@ -1,29 +1,30 @@
 require_relative "behaviour/chapter"
+require_relative "capabilities"
 require_relative "../ir"
 
 module Hecks
   module Bluebook
-    # THE CHAPTER, and no longer the namespace it lives in.
+    # The chapter, and no longer the namespace it lives in.
     #
-    # `Hecks::Bluebook` was briefly a CLASS, because dropping the
+    # `Hecks::Bluebook` was briefly a class, because dropping the
     # old `IR::` segment would otherwise have produced
     # `Bluebook::Bluebook` — a class shadowing its own enclosing module.
     # Naming the construct what the code already called it everywhere
     # (a chapter; this file was already chapter.rb) removes the clash
     # at the source, so the namespace goes back to being a module.
     #
-    # Measured before changing: `Bluebook` was used AS a class in five
+    # Measured before changing: `Bluebook` was used as a class in five
     # places and as a namespace in seventy-seven files.
     class Chapter
       include Construct
       include Behaviour::Chapter
       include Hecks::IR
 
-      # THE SCHEMA'S OWN VERSION — not a domain's `version:` (Banking's
-      # "v1", a business fact the AUTHOR chose), but the shape `to_h`
+      # **The schema's own version** — not a domain's `version:` (Banking's
+      # "v1", a business fact the author chose), but the shape `to_h`
       # itself emits. A consumer reading exported IR with no Ruby DSL to
       # cross-check against (a build-time generator, a stored snapshot)
-      # needs to know WHICH shape it's holding before it can safely
+      # needs to know which shape it's holding before it can safely
       # interpret any of the rest of it. Bump this when `to_h`'s own
       # shape changes in a way a consumer would need to know about —
       # not when a domain's own declarations change.
@@ -40,7 +41,7 @@ module Hecks
         # `bluebook.formerly_known_as` off the live Ruby object) and the
         # meta-validator's cache key is `SHA256(JSON(bluebook.to_h))` — so
         # a fact this method didn't spell was a fact two chapters
-        # differing ONLY by their old name could hash identically on,
+        # differing only by their old name could hash identically on,
         # same as read-model filters before them. Spelled here for the
         # same reason `version`/`vision` are: a plain field, present
         # (possibly nil) rather than silently absent.
@@ -50,15 +51,55 @@ module Hecks
         policies:          many(:policies),
         process_managers:  many(:process_managers),
         attaches_to:       :attaches_to,
+        # A capability this chapter answers (`provides "authorization",
+        # grant: "RoleAssignment.Assign", ...`), one row per key, in the
+        # order written. Present (possibly empty) on every chapter, the
+        # same reading `attaches_to` beside it gives.
+        provides:          -> { provides.map(&:to_h) },
         canonical_form:    -> { Expression::CanonicalForm.table }
       )
 
+      # **One row of a declared capability** — `verb` is chapter-local
+      # ("RoleAssignment.Assign"); `Behaviour::Chapter#provided_verb`
+      # qualifies it with the chapter'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
+        #   anything answering `to_h` with `capability`/`key`/`verb` entries
+        # @return [Bluebook::Chapter::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)
+
+          fields = row.to_h.transform_keys(&:to_sym)
+          new(capability: fields[:capability].to_s, key: fields[:key].to_s, verb: fields[:verb].to_s)
+        end
+      end
+
       attr_reader :name, :version, :vision, :aggregates, :policies, :process_managers,
-                  :classification, :read_models, :ports, :formerly_known_as, :attaches_to
+                  :classification, :read_models, :ports, :formerly_known_as, :attaches_to, :provides
 
+      # @param name [String, Symbol] the chapter's declared name
+      # @param version [String, Symbol, nil] the chapter's declared business version,
+      #   such as `"v1"`, or `nil` if it declares none
+      # @param vision [String, nil] the chapter's declared vision statement
+      # @param aggregates [Array<Bluebook::Aggregate>] the chapter's declared aggregates
+      # @param policies [Array<Bluebook::Policy>] every reaction declared across the
+      #   chapter's own aggregates, hoisted here
+      # @param process_managers [Array<Bluebook::ProcessManager>] the chapter's declared
+      #   process managers
+      # @param classification [String, Symbol, nil] whether this chapter is central to
+      #   its project's own domain model, or `nil` if undeclared
+      # @param read_models [Array<Bluebook::ReadModel>] the chapter's declared read models
+      # @param formerly_known_as [String, Symbol, nil] an earlier name this domain was
+      #   known under, or `nil` if it was never renamed
+      # @param attaches_to [Array<String, Symbol>] the contexts this chapter attaches to
+      # @param provides [Array<Bluebook::Chapter::Provision, Hash>] the capabilities this
+      #   chapter declares it provides
       def initialize(name:, version: nil, vision: nil, aggregates: [], policies: [],
                      process_managers: [], classification: nil, read_models: [], formerly_known_as: nil,
-                     attaches_to: [])
+                     attaches_to: [], provides: [])
         @policies         = policies
         @process_managers = process_managers
         @name       = name.to_s
@@ -71,6 +112,7 @@ module Hecks
         @classification = classification&.to_s
         @formerly_known_as = formerly_known_as&.to_s
         @attaches_to = Array(attaches_to).map(&:to_s)
+        @provides    = Array(provides).map { |row| Provision.from(row) }
         settle
       end
     end

data/lib/hecks/bluebook/command.rb

@@ -10,14 +10,12 @@ module Hecks
       include Hecks::IR
       include Behaviour::Mutation
 
-      # `sign:` — item #5 of the whole-project table-unification survey.
-      # `increment`/`decrement`'s own +1/-1 used to be re-derived from the
-      # op NAME by two independent Rust codegen scripts (rust/project/
-      # mutations.rb, rust/codegen/src/mutations.rs — a ternary on
-      # `op == "increment"` in each), even though the fact was already
-      # table-driven on the Ruby runtime side
-      # (Runtime::CommandRules::Arithmetic::MUTATION_OPS, held equal to
-      # Vocabulary::MutationOp by spec/vocabulary_conformance_spec.rb).
+      # `sign:` — item #5 of the whole-project table-unification survey:
+      # `increment`/`decrement`'s own +1/-1 comes from `Vocabulary::MutationOp`
+      # here, the same table `Runtime::CommandRules::Arithmetic::MUTATION_OPS`
+      # already reads on the Ruby runtime side, rather than a ternary on the op
+      # name re-deriving it independently in each of two Rust codegen scripts
+      # (rust/project/mutations.rb, rust/codegen/src/mutations.rs).
       # Reads `Vocabulary::MutationOp` directly (plain data, no framework
       # dependency — safe during parsing, same reason `RuleReference`'s
       # own bootstrap concerns don't apply here) rather than requiring
@@ -25,20 +23,29 @@ module Hecks
       # real layering inversion (runtime depends on bluebook, not the
       # reverse). "" (not nil) for ops with no sign, matching every other
       # optional IR text field's own absent-is-empty-string convention.
+      #
+      # @param oper [String, Symbol] the mutation's operation name, such as
+      #   `"increment"` or `"decrement"`
+      # @return [String] the operation's sign from `Vocabulary::MutationOp`
+      #   (`"+"` or `"-"`), or `""` when the op has none or is not found
       def self.sign_for(oper)
         Hecks::Vocabulary.rows("MutationOp").find { |row| row["name"] == oper.to_s }&.fetch("sign", "") || ""
       end
 
       emits_ir(target: :target, op: :op, sign: -> { Mutation.sign_for(op) })
 
-      # THE ONE GENUINELY BRANCHING EMISSION in the model: an append (or a
-      # DELEGATE — `CommandBuilder#delegates_to`'s own comment gives the
+      # The one genuinely branching emission in the model: an append (or a
+      # delegate — `CommandBuilder#delegates_to`'s own comment gives the
       # full reasoning for reusing this exact wire shape rather than
       # inventing a parallel one) binds several fields at once and carries
       # `fields:`, everything else carries a single `source:`. Declared
       # emission covers the fixed head; `super` supplies it and this adds
       # the tail, which is why a construct with a variable shape needs no
       # new mixin API.
+      # @return [Hash{Symbol => Object}] the declared emission — `super`'s fixed
+      #   head, plus `fields:` (a Hash of bound field values) for an
+      #   append-shaped op, or `source:` (`classified_source`'s own result) for
+      #   any other
       def to_h
         return super.merge(fields: appended_fields) if [:append, :delegate, :corrects].include?(op)
 
@@ -46,9 +53,9 @@ module Hecks
       end
     end
 
-    # A command, as a RUBY CLASS.
+    # A command, as a Ruby class.
     #
-    # NOT nested as a constant, and that is a finding rather than a shortcut. A
+    # Not nested as a constant, and that is a finding rather than a shortcut. A
     # command and a value object may legitimately share a name inside one
     # aggregate — the language does it six times, and means it: the command
     # `Argument` is the verb that appends to the `arguments` list whose element
@@ -56,10 +63,10 @@ module Hecks
     # So `Bluebook::Command::Argument` cannot be both, and a single constant
     # namespace cannot index a kind-ambiguous name. The same follows for
     # `hecks_fqn` : `Bluebook::Command.Argument` names both, which is why the judge's
-    # ids only work per-category, each in its own repository. IDENTITY IS
-    # (KIND, FQN), not fqn.
+    # ids only work per-category, each in its own repository. Identity is
+    # (kind, FQN), not fqn.
     #
-    # It is a declaration holder anyway, because that is where the EDGES live.
+    # It is a declaration holder anyway, because that is where the edges live.
     # `acts_on` answers with the owning construct itself — the Aggregate,
     # or the entity holder for a piece's verb — rather than the name of one.
     # The invocation door (`pizza.add_topping`) is the facade's business, a
@@ -79,8 +86,8 @@ module Hecks
         ensures:    -> { ensures.map { |rule| Expression::AstJson.rule_row(rule) } },
         mutations:  many(:mutations),
         emits:      :emits,
-        # THE LIFECYCLE STATE THIS COMMAND IS ADMISSIBLE FROM (S10, ADR
-        # 0025 — "lifecycle state becomes a command guard") — a GUARD,
+        # The lifecycle state this command is admissible from (S10, ADR
+        # 0025 — "lifecycle state becomes a command guard") — a guard,
         # not a transition: `command "Debit", from: "open"` replaces
         # `given("account is open") { status == "open" }`, checked
         # against the owning construct's own lifecycle field the same
@@ -95,6 +102,29 @@ module Hecks
         attr_reader :role, :goal, :attributes, :givens, :ensures, :mutations, :emits, :references,
                     :from, :provenance
 
+        # Mints one command as its own anonymous class, a subclass of whichever
+        # `Command`-descended class `declare` is called on.
+        #
+        # @param name [String, Symbol] the command's declared name
+        # @param role [String, nil] the command's declared role text
+        # @param goal [String, nil] the command's declared goal text
+        # @param attributes [Array<Bluebook::Attribute>] the command's declared
+        #   arguments
+        # @param givens [Array<Bluebook::Given>] the command's declared
+        #   preconditions
+        # @param ensures [Array<Bluebook::Given>] the command's declared
+        #   postconditions
+        # @param mutations [Array<Bluebook::Mutation>] the state changes this
+        #   command applies
+        # @param emits [Array<String>] the event names this command may emit
+        # @param references [String, Symbol, nil] the aggregate name this verb's
+        #   `reference_to` addresses, or `nil` for a verb declared on the
+        #   aggregate it acts on
+        # @param from [String, Array<String>, nil] the lifecycle state(s) this
+        #   command is admissible from, or `nil` for no such guard
+        # @param provenance [Object, nil] the command's declared canonical
+        #   source, captured exactly as written, or `nil` if it declares none
+        # @return [Class] the new command class
         def declare(name:, role: nil, goal: nil, attributes: [], givens: [], ensures: [],
                     mutations: [], emits: [], references: nil, from: nil, provenance: nil)
           verb = Class.new(self)
@@ -105,6 +135,21 @@ module Hecks
           verb
         end
 
+        # Assigns what the language declares, then hands off to the behaviour's
+        # own `settle` — indexing attributes, the one thing not derivable from
+        # the declaration.
+        #
+        # @param role [String, nil] see `declare`
+        # @param goal [String, nil] see `declare`
+        # @param attributes [Array<Bluebook::Attribute>] see `declare`
+        # @param givens [Array<Bluebook::Given>] see `declare`
+        # @param ensures [Array<Bluebook::Given>] see `declare`
+        # @param mutations [Array<Bluebook::Mutation>] see `declare`
+        # @param emits [Array<String>] see `declare`
+        # @param references [String, nil] see `declare`
+        # @param from [String, Array<String>, nil] see `declare`
+        # @param provenance [Object, nil] see `declare`
+        # @return [Class] self, once attributes are indexed
         def absorb(role:, goal:, attributes:, givens:, ensures:, mutations:, emits:, references:,
                    from: nil, provenance: nil)
           @role       = role