hecks 2.8.0 → 3.0.0

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

@@ -1,50 +1,37 @@
 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
-      # 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.
+      # Readings over a lifecycle's field, starting state and transition list.
       module Lifecycle
-        # Lists every state this lifecycle can be in.
+        # Every state this lifecycle can be in.
         #
-        # @return [Array<String>] every state this lifecycle can be in — the
-        #   default plus each declared transition's own target, deduplicated
+        # @return [Array<String>] the default plus each transition's target, deduplicated
         def states
           ([default] + transitions.map { |_command, t| t.target }).uniq
         end
 
-        # Finds every transition a command declares.
+        # Every transition a command declares.
         #
-        # @param command [String, Symbol] the command name to find declared
-        #   transitions for
-        # @return [Array<Bluebook::StateTransition>] every transition declared
-        #   for `command`
+        # @param command [String, Symbol]
+        # @return [Array<Bluebook::StateTransition>]
         def transitions_for(command)
           transitions.select { |name, _| name == command.to_s }.map { |_, t| t }
         end
 
-        # Finds the state a command moves the record to.
+        # The state a command moves the record to.
         #
-        # @param command [String, Symbol] the command name to find the target
-        #   state for
-        # @param current_state [String, Symbol, nil] the record's current
-        #   state, to pick the one declared transition that admits it; `nil`
-        #   to skip that check and take the first declared transition
-        # @return [String, nil] the state `command` moves the record to, or
-        #   `nil` when `command` declares no transition at all
-        # @raise [Runtime::WiringError] if `command` declares transitions but
-        #   none of them admits `current_state`
+        # @param command [String, Symbol]
+        # @param current_state [String, Symbol, nil] picks the transition that admits it;
+        #   `nil` takes the first declared transition
+        # @return [String, nil] `nil` when `command` declares no transition
+        # @raise [Runtime::WiringError] if transitions are declared but none admits `current_state`
         def target_for(command, current_state = nil)
           match_transition(command, current_state)&.target
         end
 
         private
 
-        # 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.
+        # A transition whose `from` names several states becomes one row per source state.
         def expand(command, transition)
           sources = transition.from.nil? ? [nil] : Array(transition.from)
 
@@ -58,20 +45,8 @@ module Hecks
           return nil if matches.empty?
           return matches.first unless current_state
 
-          # Not `|| matches.first` — that would 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 refuse (that
-          # refusal is `CommandRules::Admissibility#admissible_transition`'s
-          # own job, which raises `LifecycleRefused` for exactly this
-          # case rather than guessing — this module has no state subject
-          # to build that refusal message from, only the two bare
-          # values callers passed in). Zero production callers reach
-          # this branch today (both real dispatch paths that check a
-          # transition go through `admissible_transition`, not
-          # `target_for`/`match_transition`), so this raise is a
-          # backstop, not a live behaviour change — same shape as
-          # `CommandRules::Arithmetic#sign_of`'s own fix.
+          # No `|| matches.first`: that would return a target command dispatch refuses.
+          # `CommandRules::Admissibility#admissible_transition` owns the real refusal.
           matches.find { |t| applies_from?(t, current_state) } ||
             raise(Runtime::WiringError,
                   "no transition for #{command.inspect} admits state #{current_state.inspect} " \

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