hecks 1.3.0 → 1.4.0

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

@@ -1,23 +1,23 @@
 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
         def list?      = @list
         def scalar?    = !@list
         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.
         def optional? = @optional

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

@@ -3,17 +3,17 @@ 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.
         def settle
@@ -28,7 +28,25 @@ module Hecks
         def read_model(named) = @read_models.find { |model| model.name == named.to_s || model.query_name == named.to_s }
         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 used to recognise the Governance chapter by its
+        # name (`Registry#authorization_provider_for`).
+        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
+
+        def provides?(capability) = !provision(capability).nil?
+
+        # The declared verb for `key`, qualified with this chapter's own
+        # name — the spelling `Dispatcher#dispatch`/`#query` take.
+        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.
         def add_port(port)

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

@@ -3,8 +3,8 @@ require_relative "traits"
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT A COMMAND DOES. EXTENDED, not included — a command is a
-      # CLASS, one per declared verb.
+      # **What a command does**. Extended, not included — a command is a
+      # class, one per declared verb.
       module Command
         include Indexed
 
@@ -17,8 +17,8 @@ module Hecks
 
         # The construct this verb acts upon — the construct itself, not its name.
         #
-        # A verb declared on an ENTITY always acts on that piece. It never
-        # self-references, because an element is addressed THROUGH its parent —
+        # A verb declared on an entity always acts on that piece. It never
+        # self-references, because an element is addressed through its parent —
         # which means `creates?` answers true for every one of them, and reading
         # `acts_on` off `creates?` alone would report that `LedgerEntry.Amend`
         # brings a ledger entry into being. Three of banking's commands were
@@ -27,9 +27,9 @@ module Hecks
         # On an aggregate, a creating command acts on no existing root, so nil is
         # the truth: there is nothing there yet.
         def acts_on
-          # FULLY QUALIFIED, and it has to be: inside `module Behaviour`
+          # Fully qualified, and it has to be: inside `module Behaviour`
           # the bare name `Entity` resolves to Behaviour::Entity — this
-          # module's SIBLING — not to the construct. Comparing a Class to
+          # module's sibling — not to the construct. Comparing a Class to
           # a Module answers nil, so the guard silently fell through and
           # every entity verb reported acting on nothing.
           return hecks_owner if hecks_owner.is_a?(Class) && hecks_owner < Bluebook::Entity
@@ -39,8 +39,8 @@ module Hecks
 
         def creates? = @references.nil?
 
-        # EVERY REASON THIS VERB CAN REFUSE ON A RULE — the descriptions of
-        # its givens AND its ensures, the exact text the runtime quotes
+        # Every reason this verb can refuse on a rule — the descriptions of
+        # its givens and its ensures, the exact text the runtime quotes
         # after "refused — " when a guard is not met (see
         # command_rules/admissibility.rb's GivenNotMet/EnsuresNotMet). A
         # property that asks "did the runtime only ever refuse for a rule
@@ -49,8 +49,8 @@ module Hecks
         # (behavior.bluebook's Rule) and an unnamed one quotes nothing.
         def guard_descriptions = (@givens + @ensures).map(&:description).compact
 
-        # THE ARGUMENT NAME THAT ADDRESSES an instance of `aggregate_name`
-        # for THIS command — the one fact `PolicyInterpreter`'s own
+        # The argument name that addresses an instance of `aggregate_name`
+        # for this command — the one fact `PolicyInterpreter`'s own
         # `for_each` fan-out needs and, until this reading existed, had
         # to guess at (see git blame: `Behaviour::Policy
         # #fan_out_reference_key`, which hardcoded `<aggregate>_id`
@@ -58,28 +58,28 @@ module Hecks
         # addressing command as a result — `Account.Freeze`, addressed
         # by `number`/`account`, not `account_id`).
         #
-        # TWO SHAPES, the same two `CommandBuilder#reference_to` already
+        # Two shapes, the same two `CommandBuilder#reference_to` already
         # tells apart at declare time (command_builder.rb's own comment
-        # on `cross_reference` — "`as:` MEANS a named attribute... a
-        # command can point at another instance of its OWN kind"):
+        # on `cross_reference` — "`as:` means a named attribute... a
+        # command can point at another instance of its own kind"):
         #
-        #   SELF-ADDRESSING — `references == aggregate_name` (this verb
-        #   is declared ON the very aggregate it acts on, `reference_to
+        #   self-addressing — `references == aggregate_name` (this verb
+        #   is declared on the very aggregate it acts on, `reference_to
         #   Account` on a command Account itself owns). No attribute was
-        #   minted for it at all; the SAME bare key
+        #   minted for it at all; the same bare key
         #   `CommandInterpreter::ArgumentGate#reference_key` already
         #   accepts as "addressing, not describing" is reused here
         #   rather than re-derived — one door, not two.
         #
-        #   CROSS-REFERENCING — a real, declared reference-typed
-        #   attribute whose OWN target is `aggregate_name` (`customer_id`
-        #   on `Account.Open`, or whatever `as:` named it). Its NAME is
+        #   cross-referencing — a real, declared reference-typed
+        #   attribute whose own target is `aggregate_name` (`customer_id`
+        #   on `Account.Open`, or whatever `as:` named it). Its name is
         #   the key, exactly as declared — never re-derived from the
         #   target's name, because an `as:` reference's name and its
         #   target's snake case can legitimately differ (`Transfer`'s own
         #   `source`/`destination`, both `Reference<Account>`).
         #
-        # `nil` when neither shape matches — a CREATING command (nothing
+        # `nil` when neither shape matches — a creating command (nothing
         # to address yet) or one that simply never references this
         # aggregate at all. A caller minting a fan-out dispatch is
         # expected to treat `nil` as "this command cannot be addressed by
@@ -92,11 +92,11 @@ module Hecks
         end
       end
 
-      # A MUTATION'S OWN READINGS. Included (not extended) — Mutation is
+      # **A mutation's own readings**. Included (not extended) — Mutation is
       # a Struct, so these are instance methods.
       module Mutation
-        # An APPEND binds several fields at once, each from either a command
-        # ARGUMENT (a Symbol) or a LITERAL. It used to spell the Symbol bare
+        # An append binds several fields at once, each from either a command
+        # argument (a Symbol) or a literal. It used to spell the Symbol bare
         # and inspect the rest, which is the opposite of what a where-clause
         # did with the same two kinds — see Hecks::Literal.
         def appended_fields = source.transform_values { |value| Literal.render(value) }

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

@@ -3,17 +3,17 @@ require_relative "traits"
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT ONE PORT OPERATION DOES.
+      # **What one port operation does**.
       module PortOperation
         include Indexed
 
-        # An operation declares no reference of its own — the OWNER is
+        # An operation declares no reference of its own — the owner is
         # what it acts for, and `identity_attribute` is how that is found.
         def references = nil
 
-        # NEVER a creating command — a port operation always acts on an
+        # Never a creating command — a port operation always acts on an
         # aggregate that already exists (`operation.to`/`identity_attribute`
-        # both name where its RECEIVER comes from, never a birth). Answered
+        # both name where its receiver comes from, never a birth). Answered
         # explicitly, not derived from `references` the way `Command
         # #creates?` is (`references.nil?` would read every operation as
         # creating, since `references` above is unconditionally nil) —
@@ -27,10 +27,10 @@ module Hecks
           @attributes.find { |attribute| attribute.reference? && attribute.type.target_name == owner_name.to_s }
         end
 
-        # THE SAME READING `Command#addressing_key_for` gives, minus its
+        # The same reading `Command#addressing_key_for` gives, minus its
         # self-addressing branch — a port operation's `references` is
         # unconditionally nil (above), so it never means "this verb is
-        # declared ON the very aggregate it acts on" the way a command's
+        # declared on the very aggregate it acts on" the way a command's
         # does; a port operation's only path back to its owner is a real,
         # declared reference-typed attribute, which is exactly what
         # `identity_attribute` already finds. Needed for the identical
@@ -40,7 +40,7 @@ module Hecks
         def addressing_key_for(aggregate_name) = identity_attribute(aggregate_name)&.name
       end
 
-      # WHAT A PORT DOES — one finder over its declared operations.
+      # **What a port does** — one finder over its declared operations.
       module DomainPort
         def operation(named) = @operations.find { |op| op.hecks_name == named.to_s }
       end

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

@@ -3,8 +3,8 @@ require_relative "traits"
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT AN ENTITY DOES. EXTENDED, not included — an entity is a
-      # CLASS, so this is singleton behaviour.
+      # **What an entity does**. Extended, not included — an entity is a
+      # class, so this is singleton behaviour.
       #
       # `settle` is the same seam an Aggregate has, reached from `absorb`
       # rather than from a constructor because a declared entity is built
@@ -29,26 +29,26 @@ module Hecks
           @queries_by_name  = index_by_hecks_name(@queries)
         end
 
-        # S17, ADR 0026 — `@entities`, now genuinely NESTED entities
+        # S17, ADR 0026 — `@entities`, now genuinely nested entities
         # (Dispatch, inside Handler) rather than always `[]`. Kept as a
         # real reader rather than a hardcoded empty list for two
         # reasons at once: `Value::Coercion#for_attribute` calls
-        # `.entities` on WHATEVER OWNER it is handed — an aggregate's or
-        # an entity's own — the moment it meets ANY `list_of(...)`
+        # `.entities` on whatever owner it is handed — an aggregate's or
+        # an entity's own — the moment it meets any `list_of(...)`
         # attribute (entity-typed or not — `hydrate_entity_list`'s own
         # fallback, `return value unless entity`, only runs once
         # `.entities` has already answered) ; and `EntityInterpreter`
-        # now walks a DOTTED chain of entities one level at a time
+        # now walks a dotted chain of entities one level at a time
         # (`walk_entity_chain`) exactly the way an aggregate's own
         # `.entities` is walked for its direct children. Entity's own
         # header comment already promises it stays "structurally
         # interchangeable with an aggregate" for exactly this reason.
         def entities = @entities || []
 
-        # A piece OWNS the verbs declared on it, so they can state an
+        # A piece owns the verbs declared on it, so they can state an
         # identity — `Banking::Account.Ledger.Deposit` rather than a
         # command that cannot say what it belongs to. Separate from
-        # `settle` because `declare` stamps AFTER absorbing, once the
+        # `settle` because `declare` stamps after absorbing, once the
         # subclass that will own them exists. `@entities` too now
         # (S17, ADR 0026) — a nested entity states its own owner chain
         # exactly the way a nested command does.

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

@@ -1,7 +1,7 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT A HECKSAGON DOES — the lookups over its declared binds.
+      # **What a hecksagon does** — the lookups over its declared binds.
       module Hecksagon
         # Aggregate-specific bind wins when one was declared; otherwise
         # falls back to a domain-level default (`b.aggregate.nil?` — see
@@ -21,7 +21,7 @@ module Hecks
         end
       end
 
-      # WHAT A WORLD DOES — settings lookup, with the adapter-specific
+      # **What a world does** — settings lookup, with the adapter-specific
       # entry falling back to the verb's own.
       module World
         def for_verb(verb) = @settings.fetch(verb.to_s, {})
@@ -30,13 +30,13 @@ module Hecks
         # end`) only answers for the adapter it actually names — falling
         # back to it unconditionally applies one adapter's settings to an
         # unrelated one. Real, corpus-caught bug: a hecksagon binding two
-        # aggregates to two different adapters under the SAME verb (one to
+        # aggregates to two different adapters under the same verb (one to
         # Heki, one to Memory) sent Memory's lookup down Heki's generic
         # entry, then failed `check_settings` with "Memory does not
         # declare :dir" — the generic entry's own `settings[:adapter]`
         # names Heki, not Memory, so the fallback was never actually for
         # this bind. `{}` is exactly right when nothing was configured for
-        # THIS adapter — Memory, which takes no values at all.
+        # this adapter — Memory, which takes no values at all.
         def for_binding(verb, adapter)
           qualified = @settings["#{verb}:#{adapter.to_s.downcase}"]
           return qualified if qualified

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

@@ -1,8 +1,8 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT A LIFECYCLE DOES. Its declared half is a field, a starting
-      # state and a transition list. Everything here READS that — which
+      # **What a lifecycle does**. Its declared half is a field, a starting
+      # state and a transition list. Everything here reads that — which
       # states exist, which transition a command takes, and how one
       # declared transition expands into the several rows the emission
       # carries when `from` names more than one source state.
@@ -21,7 +21,7 @@ module Hecks
 
         private
 
-        # ONE DECLARED TRANSITION IS SEVERAL ROWS when `from` names more
+        # One declared transition is several rows when `from` names more
         # than one source state — the emission carries them flat, so the
         # fan-out happens here rather than in whatever reads it.
         def expand(command, transition)
@@ -37,8 +37,8 @@ module Hecks
           return nil if matches.empty?
           return matches.first unless current_state
 
-          # NOT `|| matches.first` — that used to silently hand back an
-          # ARBITRARY declared transition for `command` whenever none of
+          # Not `|| matches.first` — that used to silently hand back an
+          # arbitrary declared transition for `command` whenever none of
           # them actually admitted `current_state`, picking a `target`
           # that command dispatch would in fact have refused (that
           # refusal is `CommandRules::Admissibility#admissible_transition`'s

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

@@ -1,10 +1,10 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT A POLICY DOES. Its declared half is four plain fields; these
+      # **What a policy does**. Its declared half is four plain fields; these
       # are the readings taken off them.
       module Policy
-        # The BLUEBOOK's name for this construct, asked the same way of a class
+        # 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.
         def hecks_name = @name
@@ -13,18 +13,18 @@ module Hecks
 
         def event_name = Naming.unqualified(@on_event)
 
-        # WHETHER THIS POLICY FANS OUT — `for_each` names a query, and a
+        # 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.
         def fans_out? = !@for_each.to_s.empty?
 
-        # WHETHER THIS POLICY IS GUARDED — a non-empty `where` decides
+        # Whether this policy is guarded — a non-empty `where` decides
         # whether the policy fires at all, read against the triggering
         # event's own payload.
         def guarded? = !@where.to_s.empty?
 
-        # THE STRUCTURED FORM OF `where`, derived once — the same tree
+        # 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
@@ -42,9 +42,9 @@ module Hecks
         # it; an unmet where is a silent skip).
         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:
+        # 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`
+        # 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.
@@ -54,13 +54,13 @@ module Hecks
           [domain, aggregate, query_name]
         end
 
-        # THE ARGUMENT NAME A FAN-OUT DISPATCH mints each matched row's id
-        # under used to be minted HERE, unconditionally, as `<aggregate>
-        # _id` — a real bug: a target command declared ON the very
+        # The argument name a fan-out dispatch mints each matched row's id
+        # under used to be minted here, unconditionally, as `<aggregate>
+        # _id` — a real bug: a target command declared on the very
         # aggregate it self-references (`Account.Freeze`) is addressed by
-        # its OWN identity field's name, not a synthetic foreign key, and
+        # its own identity field's name, not a synthetic foreign key, and
         # every such dispatch refused. That question is not this policy's
-        # to answer at all — it depends on the TARGET COMMAND'S OWN
+        # to answer at all — it depends on the target command's own
         # declared shape, not on the aggregate name alone — so it now
         # lives on `Behaviour::Command#addressing_key_for`, asked of the
         # resolved target command by `PolicyInterpreter#addressing_key_for`.

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

@@ -1,13 +1,13 @@
 module Hecks
   module Bluebook
     module Behaviour
-      # WHAT A PROCESS MANAGER DOES. Its declared half is the trigger,
+      # **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.
+      # derived from the handler that answers a refusal, not declared.
       module ProcessManager
         def hecks_name = @name
 
-        # THE LEG THAT ANSWERS — selected by (event, current state), C10.3
+        # 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
@@ -25,7 +25,7 @@ module Hecks
 
         def handles?(event) = @handlers.any? { |h| h.event_type == event.to_s }
 
-        # WHETHER A STATE IS ONE THIS PROCEDURE DECLARES — asked of a value
+        # 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
@@ -43,13 +43,13 @@ module Hecks
           leg = handler_for(Bluebook::ProcessManager::REFUSED)
           return nil unless leg
 
-          # `compensations` — a STATIC PREVIEW, declaration order, not
+          # `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
+          # 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

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

@@ -1,7 +1,7 @@
 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
         def attribute(named) = @attributes.find { |a| a.name == named.to_sym }
       end

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

@@ -1,7 +1,7 @@
 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
         def group_by_fields = @group_by.map { |row| row[:field].to_sym }
@@ -14,11 +14,11 @@ module Hecks
 
         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.
@@ -33,7 +33,7 @@ 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.
@@ -43,13 +43,13 @@ module Hecks
           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)
 

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,20 +11,20 @@ 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
@@ -35,7 +35,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,19 +43,19 @@ 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.
         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.
         def index_by_hecks_name(collection)
           collection.to_h { |held| [held.hecks_name, held] }
         end
@@ -65,7 +65,7 @@ module Hecks
         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

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

@@ -1,29 +1,29 @@
 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
+        # 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
+        # judge it, the same way an empty attribute name survives into the IR
         # and is judged there.
         def closed_set? = @closed_set
 
         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`/