hecks 2.8.0 → 2.9.0

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

@@ -1,53 +1,36 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # **What a policy does**. Its declared half is four plain fields; these
-      # are the readings taken off them.
+      # Readings over a policy's declared fields.
       module Policy
-        # The bluebook's name for this construct, asked the same way of a class
-        # that has crossed over and of an IR object that has not. Collapses into
-        # Construct when this one crosses.
+        # The bluebook's name for this construct.
         #
-        # @return [String] this policy's declared name
+        # @return [String]
         def hecks_name = @name
 
         # The domain-and-aggregate prefix of the triggering event's name.
         #
-        # @return [String, nil] the part of `on_event` before its first `.`
-        #   (the `"Domain::Aggregate"` prefix), or `nil` when `on_event`
-        #   carries no dot
+        # @return [String, nil] the part of `on_event` before its first `.`, or `nil` if none
         def event_qualifier = Naming.qualifier(@on_event)
 
-        # The bare name of the triggering event, without its domain/aggregate
-        # prefix.
+        # The triggering event's bare name, without its prefix.
         #
-        # @return [String] the part of `on_event` after its first `.` (the
-        #   bare event name), or the whole string when it carries no dot
+        # @return [String]
         def event_name = Naming.unqualified(@on_event)
 
-        # Whether this policy fans out — `for_each` names a query, and a
-        # non-empty one turns a single reaction into one dispatch per row
-        # the query answers. Read by the interpreter that runs the fan-out
-        # and by the property that checks it dispatched once per row.
+        # Whether `for_each` names a query, turning one reaction into a dispatch per row.
         #
-        # @return [Boolean] whether `for_each` names a query
+        # @return [Boolean]
         def fans_out? = !@for_each.to_s.empty?
 
-        # Whether this policy is guarded — a non-empty `where` decides
-        # whether the policy fires at all, read against the triggering
-        # event's own payload.
+        # Whether a non-empty `where` decides if the policy fires at all.
         #
-        # @return [Boolean] whether `where` is declared and non-empty
+        # @return [Boolean]
         def guarded? = !@where.to_s.empty?
 
-        # The structured form of `where`, derived once — the same tree
-        # `AstJson.emit_predicate` spells for every rule row, memoized
-        # here because a policy is consulted once per event, not once per
-        # boot. Nil when there is no `where`, exactly as the wire carries
-        # it.
+        # The structured form of `where`, memoized because a policy is consulted once per event.
         #
-        # @return [Hash, nil] the JSON-shaped boolean AST for `where`, or
-        #   `nil` when this policy is not guarded
+        # @return [Hash, nil] `nil` when the policy is not guarded
         def where_ast
           if defined?(@where_ast)
             @where_ast
@@ -56,39 +39,27 @@ module Hecks
           end
         end
 
-        # The rule-shaped reading of the guard, for `Evaluator.call_rule`
-        # — a policy's `where` has no description (nothing refuses with
-        # it; an unmet where is a silent skip).
+        # The guard as a rule for `Evaluator.call_rule`; it has no description because an
+        # unmet `where` is a silent skip.
         #
-        # @return [Bluebook::Given] the guard as a rule, with no description
-        #   and its `ast` already resolved via `where_ast`
+        # @return [Bluebook::Given]
         def where_rule = @where_rule ||= Given.new(description: nil, canonical: @where, ast: where_ast)
 
-        # The fan-out query's route, split the way the runtime runs it:
-        # `[query_domain, aggregate_name, query_name]`. The query runs
-        # against the triggering event's own domain unless `for_each`
-        # names one ("Domain::Aggregate.query"). Deliberately independent
-        # of `across`/`target_domain`, which name where `trigger` fires,
-        # not where the fan-out's own query runs.
+        # The fan-out query's route, split the way the runtime runs it.
         #
-        # @param default_domain [String, Symbol] the triggering event's own
-        #   domain, used when `for_each` names no domain of its own
-        # @return [Array(String, String, String)] `[domain, aggregate_name,
-        #   query_name]` the fan-out query resolves against
+        # The query runs in the triggering event's domain unless `for_each` names one
+        # ("Domain::Aggregate.query"); it is independent of `across`/`target_domain`.
+        #
+        # @param default_domain [String, Symbol] the triggering event's domain
+        # @return [Array(String, String, String)] `[domain, aggregate_name, query_name]`
         def for_each_route(default_domain)
           path, query_name = @for_each.to_s.split(".", 2)
           domain, aggregate = path.to_s.include?("::") ? path.split("::", 2) : [default_domain.to_s, path]
           [domain, aggregate, query_name]
         end
 
-        # The argument name a fan-out dispatch mints each matched row's id
-        # under is not minted here — it depends on the target command's own
-        # declared shape (a target command declared on the very aggregate it
-        # self-references, such as `Account.Freeze`, is addressed by its own
-        # identity field's name, not a synthetic foreign key), not on the
-        # aggregate name alone, so it lives on
-        # `Behaviour::Command#addressing_key_for`, asked of the resolved
-        # target command by `PolicyInterpreter#addressing_key_for`.
+        # The argument name for each fan-out row's id is not minted here: it depends on the
+        # target command's declared shape, so it lives on `Behaviour::Command#addressing_key_for`.
       end
     end
   end

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

@@ -1,96 +1,69 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # **What a process manager does**. Its declared half is the trigger,
-      # the states and the handlers; the compensation half — `saga` — is
-      # derived from the handler that answers a refusal, not declared.
+      # Readings over a process manager's trigger, states and handlers.
+      # Its `saga` is derived from the handler that answers a refusal, not declared.
       module ProcessManager
         # The bluebook's name for this construct.
         #
-        # @return [String, nil] the process manager's declared name, or `nil` before it
-        #   is set
+        # @return [String, nil]
         def hecks_name = @name
 
-        # The leg that answers — selected by (event, current state), C10.3
-        # (docs/semantics/bluebook-semantics.md). Two legs may answer the
-        # same event from different states; which one runs is decided by
-        # the state the instance is in, never by declaration order. With
-        # no `state` the reading is declarative — "does any leg answer this
-        # event, and what is it" — for callers that ask about the
-        # procedure rather than an instance (`saga`, the outbox's consumer
-        # selection). Build refuses two legs on one (event, state) pair
-        # (`ProcessManagerBuilder#validate!`), so a stated lookup is
-        # unambiguous by construction.
+        # The leg that answers an event from a state (C10.3, docs/semantics/bluebook-semantics.md).
         #
-        # @param event [String, Symbol] the triggering event's name
-        # @param state [String, Symbol, nil] the instance's current state; `nil` asks
-        #   declaratively, ignoring state
-        # @return [Bluebook::ProcessManagerHandler, nil] the matching handler row, or `nil`
-        #   if no declared leg answers this (event, state) pair
+        # State, never declaration order, picks between legs; build refuses two legs on one
+        # (event, state) pair. With no `state` the lookup is declarative: does any leg answer.
+        #
+        # @param event [String, Symbol]
+        # @param state [String, Symbol, nil] the instance's current state; `nil` ignores state
+        # @return [Bluebook::ProcessManagerHandler, nil]
         def handler_for(event, state = nil)
           @handlers.find { |h| h.event_type == event.to_s && (state.nil? || h.from_state == state.to_s) }
         end
 
-        # Finds every declared leg for an event, regardless of source state.
+        # Every declared leg for an event, regardless of source state.
         #
-        # @param event [String, Symbol] the triggering event's name
-        # @return [Array<Bluebook::ProcessManagerHandler>] every handler row declared for
-        #   `event`; `[]` if none is declared
+        # @param event [String, Symbol]
+        # @return [Array<Bluebook::ProcessManagerHandler>]
         def handlers_for(event) = @handlers.select { |h| h.event_type == event.to_s }
 
-        # Says whether any declared leg answers an event.
+        # Whether any declared leg answers an event.
         #
-        # @param event [String, Symbol] the triggering event's name
-        # @return [Boolean] whether any handler row is declared for `event`
+        # @param event [String, Symbol]
+        # @return [Boolean]
         def handles?(event) = @handlers.any? { |h| h.event_type == event.to_s }
 
-        # Whether a state is one this procedure declares — asked of a value
-        # a real run left a saga instance holding (its live or rehydrated
-        # state), the way `Lifecycle#states` is asked of an aggregate's
-        # resting field. A rehydrated instance in a state no handler could
-        # have reached is corruption the durable round-trip introduced.
+        # Whether a state is one this procedure declares. A rehydrated instance in an
+        # undeclared state is corruption from the durable round-trip.
         #
-        # @param state [String, Symbol] the state to check
-        # @return [Boolean] whether `state` is one of this procedure's declared states
+        # @param state [String, Symbol]
+        # @return [Boolean]
         def declares_state?(state) = @states.map(&:to_s).include?(state.to_s)
 
-        # Names the payload field a triggering event's instances are correlated by.
+        # The payload field a triggering event's instances are correlated by.
         #
-        # @return [Symbol] the head of `correlates_by` — the part before the first `.`
+        # @return [Symbol] the part of `correlates_by` before the first `.`
         def correlation_head = @correlates_by.to_s.split(".").first.to_sym
 
-        # The compensation half of a procedure, read off the handler that
-        # answers `REFUSED`.
-        #
-        # nil for a procedure with no answer to a refusal, which is a legitimate
-        # thing to be — a hiring pipeline cannot un-interview anybody.
+        # The compensation half, read off the handler that answers `REFUSED`.
         #
-        # @return [Bluebook::Saga, nil] the derived saga, or `nil` if no handler answers
-        #   `REFUSED`
+        # @return [Bluebook::Saga, nil] `nil` when no handler answers a refusal, which is
+        #   legitimate: a hiring pipeline cannot un-interview anybody
         def saga
           leg = handler_for(Bluebook::ProcessManager::REFUSED)
           return nil unless leg
 
-          # `compensations` — a static preview, declaration order, not
-          # one instance's own runtime history (which legs a given
-          # instance actually completed is per-instance state,
-          # `SagaInterpreter`'s own `completed_compensations`, not a
-          # fact `Saga` — a pure declaration reading — could ever hold).
-          # Every `compensates` any handler's own dispatch declares,
-          # forward declaration order, then whatever this leg's own
-          # hand-written body still lists — coexistence, not replacement
-          # (`ProcessManagerBuilder::HandlerBuilder#dispatch_impl`'s own
-          # comment): a saga can derive some of its compensation and
-          # still hand-write the rest for what isn't expressible as
-          # "undo command X".
+          # A static preview in declaration order, not one instance's runtime history.
+          # Derived `compensates` come first, then the leg's hand-written body, so a saga
+          # can derive some compensation and hand-write the rest.
           derived = handlers.flat_map { |handler| handler.dispatches.filter_map(&:compensates) }
           Bluebook::Saga.new(trigger: Bluebook::ProcessManager::REFUSED, from_state: leg.from_state,
                              to_state: leg.to_state, compensations: derived + leg.dispatches)
         end
 
-        # Says whether this procedure declares a handler for `REFUSED`.
+        # Whether this procedure declares a handler for `REFUSED`.
         #
-        # @return [Boolean] whether this procedure has a derivable saga
+        # @return [Boolean]
         def saga? = !saga.nil?
       end
     end

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

@@ -1,20 +1,31 @@
 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
+        # Every reduction a read model may declare over its one eligible collection, each
+        # naming the ivar that holds its declared value and the word it reads back as in a
+        # refusal message. A read model reports one shape, so at most one of these is ever set.
+        REDUCTION_FIELDS = {
+          count: "count", median_field: "median", sum_field: "sum", avg_field: "avg",
+          min_field: "min", max_field: "max", percentile_field: "percentile",
+          any_field: "any", all_field: "all"
+        }.freeze
+
+        # @return [Boolean] whether this read model declares any reduction (`REDUCTION_FIELDS`)
+        def reducing? = REDUCTION_FIELDS.each_key.any? { |ivar| instance_variable_get(:"@#{ivar}") }
+
         # 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 }
 
-        # Reports whether this read model's `group_by` names every identity head
-        # of the aggregate it groups (ADR 0061, decision D1).
+        # Reports whether this read model's `group_by` names every identity
+        # head of the aggregate it groups (ADR 0061).
         #
-        # Such a key path cannot be shared by two rows, so it is accepted from the
-        # declaration alone and never checked for a collision at dispatch. Any
-        # other key path is checked per request.
+        # Such a key path can't be shared by two rows, so uniqueness is accepted
+        # from the declaration alone rather than checked per request.
         #
         # @param aggregate [Bluebook::Aggregate, nil] the aggregate of this read
         #   model's one many-side head
@@ -27,10 +38,8 @@ module Hecks
           !identity.empty? && (identity - group_by_fields).empty?
         end
 
-        # `!!` 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`.
+        # `!!` guards against a future caller constructing a ReadModel by
+        # hand with `count: false` rather than the normalised `nil`.
         #
         # @return [Boolean] whether this read model reduces to a row count
         def count? = !!@count
@@ -40,14 +49,9 @@ module Hecks
         # @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,
-        # 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
-        # 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.
+        # Which gathered heads the filtering applies to (ADR 0055): with one
+        # many-side head every untargeted option applies to it; with several,
+        # only the ones a targeted option names via `on:` 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
@@ -61,10 +65,7 @@ module Hecks
           targets.filter_map { |target| many.find { |head| head[:aggregate] == target.to_s } }.map { |head| head[:as] }
         end
 
-        # The pre-`on:` reading (ADR 0055), unchanged: with exactly one
-        # 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
+        # Split out only to keep `filtered_head_names` 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
@@ -73,18 +74,11 @@ module Hecks
         #   declared, else `[]`
         def single_filtered_head_name(many)
           declared = wheres.any? || order_by || limit || offset || authorization&.tenant ||
-                     @group_by.any? || count? || @median_field
+                     @group_by.any? || reducing?
           declared ? [many.first[:as]] : []
         end
 
-        # 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`
-        # resolves to `head_as`'s own aggregate.
+        # Filtering options scoped to one included aggregate head (ADR 0055).
         FilteredOptions = Struct.new(:wheres, :order_by, :limit, :offset, :null_semantics)
 
         # Scopes this read model's filtering options down to one included head.

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

@@ -1,35 +1,17 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # 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
-      # PortOperation — and the identity derivation twice, byte for byte,
-      # for as long as those constructs have existed. Splitting holding
-      # from doing is what made them visible: the same method in four
-      # 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
-      # one like Command), because every one of them reads instance
-      # variables and nothing else.
+      # Behaviour shared by more than one construct. Each module works whether it is included
+      # (an ordinary object like Aggregate) or extended (a class-shaped one like Command),
+      # because it reads only instance variables.
 
       # A construct whose identity is a join of declared paths.
       #
-      # 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
-      # no single head, and answering with the first would be a guess ; the
-      # readers that need all of them ask for `identity_heads`.
+      # Several paths mean the identity is made of several facts. `identity_heads` are the
+      # attributes those paths start at; `identified_by` is the single head, set only when there
+      # is exactly one, since a composite has no single head and the first would be a guess.
       module Identified
-        # Derives `identity_paths`, `identity_heads` and the single-head form of
-        # `identified_by` from the declared `identified_by` path(s).
+        # Derives `identity_paths`, `identity_heads` and the single-head `identified_by`.
         #
         # @return [void]
         def derive_identity
@@ -41,72 +23,53 @@ module Hecks
 
       # 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
-      # linear scan repeated on every call was doing work the declared shape
-      # 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
-      # that differs: an aggregate has five, an entity three, a command one.
+      # Indexed once because declarations are final when the construct exists. `index_by_name`
+      # takes the collections to index since which ones a construct has differs per construct.
       module Indexed
-        # Keyed by symbol — an attribute is asked for by its declared
-        # symbol name everywhere in the runtime.
+        # Keyed by symbol, the way the runtime asks for an attribute.
         #
-        # @param attributes [Array<Bluebook::Attribute>] the construct's declared
-        #   attributes
+        # @param attributes [Array<Bluebook::Attribute>]
         # @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
-        # 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.
+        # Keyed by string and by `hecks_name`, since such a construct's Ruby `name` is a
+        # constant path or nothing at all for an anonymous class.
         #
-        # @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`
+        # @param collection [Array<#hecks_name>] value objects, commands or queries
+        # @return [Hash{String => Object}]
         def index_by_hecks_name(collection)
           collection.to_h { |held| [held.hecks_name, held] }
         end
 
-        # Finds a declared attribute by its declared name.
+        # Finds a declared attribute by 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
+        # @param named [String, Symbol]
+        # @return [Bluebook::Attribute, nil]
         def attribute(named) = @attributes_by_name[named.to_sym]
 
-        # Finds a declared command by its declared name.
+        # Finds a declared command by 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
+        # @param named [String, Symbol]
+        # @return [Class, nil] a `Bluebook::Command` subclass
         def command(named)   = @commands_by_name[named.to_s]
 
-        # Finds a declared query by its declared name.
+        # Finds a declared query by 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
+        # @param named [String, Symbol]
+        # @return [Bluebook::Query, nil]
         def query(named)     = @queries_by_name[named.to_s]
       end
 
       # 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.
+      # Owner links are read lazily (hecks_fqn, Reference#resolve), so stamping when the
+      # construct is complete is early enough and needs no help from outside.
       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=`
+        # @param children [Array<#hecks_owner=>] arrays or bare objects, flattened first
         # @return [void]
         def stamp(*children)
           children.flatten.each { |child| child.hecks_owner = self }

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

@@ -1,17 +1,10 @@
 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
-      # behaviour is singleton behaviour, and the holding half's `absorb`
-      # is what a generated constructor would be.
+      # Behaviour of a value object; extended rather than included, since each shape is
+      # its own class.
       module ValueObject
-        # 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.
+        # Recorded as its own fact so an empty `one_of` differs from no `one_of` at all.
         #
         # @return [Boolean] whether this value object declares `one_of`, even
         #   if left empty
@@ -24,21 +17,9 @@ module Hecks
         #   `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
-        # 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.
+        # A single-attribute value object (EmailAddress{address}) names a scalar, not a group.
         #
-        # `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
-        # 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.
+        # A closed set's discriminant column is a different question and may span attributes.
         #
         # @return [Bluebook::Attribute, nil] this value object's only
         #   attribute, or `nil` when it has zero or more than one

data/lib/hecks/bluebook/capabilities.rb

@@ -1,65 +1,33 @@
 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 | :port_operation   the kind of verb that key must name
-    #
-    # A `:port_operation` verb is spelled `"Aggregate.Port.Operation"` and names
-    # an operation the chapter's hecksagon declares on one of its aggregates.
-    # The hecksagon attaches after the chapter is built, so the chapter itself
-    # only checks the spelling; `Registry#verify!` checks the operation exists.
+    # What a chapter may declare it provides — trusted in place of a literal
+    # chapter-name check by role checks, adapters and the fuzzer.
     module Capabilities
       AUTHORIZATION = "authorization".freeze
-      # Who may sign in, and with what role — rust/host's Google-OAuth
-      # provision/member_rows resolve this instead of an env var naming
-      # the aggregate (HECKS_MEMBERSHIP_AGGREGATE). Same declared-
-      # not-named shape `AUTHORIZATION` already is for Governance.
+      # Who may sign in and with what role, resolved by declaration rather
+      # than an env var naming the aggregate.
       MEMBERSHIP = "membership".freeze
-      # A stable organizational identity, independent of how it was
-      # authenticated — recognised by declaration, not the literal name
-      # "Identity". Same declared-not-named shape `AUTHORIZATION` already
-      # is. rust/host does not build this chapter's payloads; any field
-      # mapping lives on the consuming hecksagon's `translates` ACL.
+      # A stable organizational identity, recognised by declaration rather
+      # than the literal name "Identity".
       IDENTITY = "identity".freeze
-      # Guest-facing newsletter signup: who subscribed, confirmed, or left —
-      # recognised by declaration, not the literal chapter name
-      # "Newsletter". rust/host's newsletter routes dispatch these verbs
-      # and read the subscribing aggregate's instances off `subscribe`.
+      # Guest newsletter signups, recognised by declaration rather than the
+      # literal chapter name "Newsletter".
       NEWSLETTER = "newsletter".freeze
-      # Sending an issue to the confirmed subscribers: the decision to send
-      # and the record of each email handed to the mail provider. A separate
-      # capability from `NEWSLETTER` so a chapter that only takes signups
-      # declares nothing more; rust/host serves the send route only when a
-      # chapter declares this one as well.
+      # 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: start one, then
-      # hear the processor's verdict — recognised by declaration, not the
-      # literal chapter name "Payments". rust/host's checkout and webhook
-      # routes dispatch these verbs and read the paying aggregate's
-      # instances off `initiate`. The two verdicts are hecksagon port
-      # operations (the processor's webhook, translated into this chapter's
-      # vocabulary), not commands.
+      # 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 for them — recognised
-      # by declaration, not the literal aggregate names "Event" and
-      # "Registration". rust/host's event and registration routes dispatch
-      # these verbs; the aggregates they name are the event and the
-      # registration.
+      # 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: connect it, drop
-      # it, pause it, and switch taking payments on or off — recognised by
-      # declaration, not the literal name "PaymentConnection". rust/host's
-      # payments routes dispatch these verbs; the connection aggregate is
-      # the one `connect` names.
+      # A business's connection to its payment processor, recognised by
+      # declaration rather than the literal name "PaymentConnection".
       PAYMENT_CONNECTION = "payment_connection".freeze
 
       CONTRACTS = {