hecks 1.4.0 → 1.5.0

data/lib/hecks/bluebook/hexagon.rb

@@ -4,17 +4,36 @@ require_relative "../ir"
 module Hecks
   module Bluebook
     Port = Struct.new(:name, :verb, :signal, :answers, keyword_init: true) do
+      # Says whether this port answers its verb with a return value.
+      #
+      # @return [Boolean] whether `signal` is `:reply`
       def reply?  = signal == :reply
+
+      # Says whether this port answers its verb by taking effect, with no return value.
+      #
+      # @return [Boolean] whether `signal` is `:effect`
       def effect? = signal == :effect
     end
 
     Adapter = Struct.new(:name, :port, :fields, :secrets, keyword_init: true) do
+      # Says whether this adapter declares a field, plain or secret.
+      #
+      # @param field [Symbol, String] the field to check
+      # @return [Boolean] whether `field` is one of this adapter's own `fields` or `secrets`
       def declares?(field) = all_fields.include?(field.to_sym)
 
+      # Lists every field this adapter declares, plain and secret alike.
+      #
+      # @return [Array<Symbol>] every field this adapter declares, `fields` and `secrets`
+      #   combined
       def all_fields = (fields || []) + (secrets || [])
     end
 
     Bind = Struct.new(:aggregate, :verb, :adapter, :role, keyword_init: true) do
+      # Names the aggregate this bind applies to.
+      #
+      # @return [String] this bind's aggregate name, demodulised, or `""` for a
+      #   domain-level default bind with no aggregate
       def aggregate_name = Naming.demodulise(aggregate)
     end
 
@@ -37,6 +56,14 @@ module Hecks
 
       attr_reader :domain, :binds, :subscriptions, :framework_members, :vendored_bluebooks
 
+      # @param domain [String, Symbol] the domain this hecksagon wires
+      # @param binds [Array<Bluebook::Bind>] the declared adapter binds
+      # @param subscriptions [Array<String, Symbol>] the external events this domain
+      #   subscribes to
+      # @param framework_members [Array<String, Symbol>] the framework members
+      #   (`Governance`, `Identity`, ...) this domain attaches
+      # @param vendored_bluebooks [Array<String, Symbol>] the vendored embryonaut
+      #   bluebook package names this domain attaches
       def initialize(domain:, binds: [], subscriptions: [], framework_members: [], vendored_bluebooks: [])
         @domain             = domain.to_s
         @binds              = binds
@@ -59,6 +86,13 @@ module Hecks
 
       attr_reader :domain, :realm, :latest, :settings
 
+      # @param domain [String, Symbol] the domain this world configures
+      # @param realm [String, Symbol, nil] the declared realm/version marker, or `nil`
+      #   if none is declared
+      # @param latest [String, Symbol, nil] the declared latest-version marker, or `nil`
+      #   if none is declared
+      # @param settings [Hash] the declared adapter bind settings, keyed by verb and,
+      #   for a qualified entry, `"verb:adapter"`
       def initialize(domain:, realm: nil, latest: nil, settings: {})
         @domain   = domain.to_s
         @realm    = realm&.to_s

data/lib/hecks/bluebook/lifecycle.rb

@@ -9,6 +9,9 @@ module Hecks
     class StateTransition
       attr_reader :target, :from
 
+      # @param target [String, Symbol] the state this transition moves the record to
+      # @param from [String, Symbol, Array<String, Symbol>, nil] the state, or states, this
+      #   transition applies from; `nil` means any current state admits it
       def initialize(target:, from: nil)
         @target = target.to_s
         @from   = case from
@@ -18,6 +21,10 @@ module Hecks
                   end
       end
 
+      # Says whether this transition is guarded to specific source states.
+      #
+      # @return [Boolean] whether this transition is guarded to specific source states,
+      #   rather than applying from any current state
       def constrained? = !@from.nil?
     end
 
@@ -41,6 +48,10 @@ module Hecks
 
       attr_reader :field, :default, :transitions
 
+      # @param field [Symbol, String] the attribute this state machine lives on
+      # @param default [String, Symbol] the state a new record starts in
+      # @param transitions [Array<Array(String, Bluebook::StateTransition)>] each declared
+      #   `command name, StateTransition` pair, in declaration order
       def initialize(field:, default:, transitions: [])
         @field       = field.to_sym
         @default     = default.to_s

data/lib/hecks/bluebook/meta_validator/adapter_judge.rb

@@ -11,6 +11,7 @@ module Hecks
       class AdapterJudge
         attr_reader :refusals
 
+        # @param adapter [Bluebook::Adapter] the built adapter to judge
         def initialize(adapter)
           @adapter  = adapter
           @refusals = []

data/lib/hecks/bluebook/meta_validator/judge.rb

@@ -3,18 +3,19 @@ module Hecks
     module MetaValidator
       # Offers every declaration in a built bluebook to the meta-domain.
       #
-      # This used to be one hand-written branch per category, and the cost of that
-      # shape was fourteen verbs the language declared and the judge never offered
-      # — among them `Command.Argument` and `ValueObject.Field`, so a command's own
-      # arguments and a value object's own fields were never judged. Every rule
-      # hanging off them was decoration. Nothing went red, because a branch that
-      # does not exist cannot fail.
+      # There are no hand-written branches, one per category: that shape's
+      # real cost is any verb the language declares that the judge never
+      # offers — a branch nobody wrote for it — going undetected, since a
+      # branch that does not exist cannot fail. `Command.Argument` and
+      # `ValueObject.Field` were both admitted that way once, undetected;
+      # every rule hanging off them was decoration until offered for real.
       #
-      # So there are no branches. The judge walks: it reads the plan the language
-      # makes of itself (Plan), and for each node offers the creating command, then
-      # each list through the command that appends to it, then each child. A verb
-      # in the plan with no offer is now impossible — there is no branch left in
-      # which to forget one, and spec/judge_coverage_spec holds it to that.
+      # So instead the judge walks: it reads the plan the language makes of
+      # itself (Plan), and for each node offers the creating command, then
+      # each list through the command that appends to it, then each child. A
+      # verb in the plan with no offer is now impossible — there is no
+      # branch left in which to forget one, and spec/judge_coverage_spec
+      # holds it to that.
       #
       # What is not uniform lives in Readings, and only where the IR's shape
       # differs from the language's. Naming differences do not appear at all: the
@@ -61,6 +62,8 @@ module Hecks
         # not a curiosity, so the runtime is simply readable.
         attr_reader :runtime
 
+        # @param bluebook [Object] a built bluebook chapter graph, as
+        #   `MetaValidator.call` receives it
         def initialize(bluebook)
           @bluebook = bluebook
           @refusals = []
@@ -160,12 +163,12 @@ module Hecks
 
         # Declared before detailed, for every set of siblings.
         #
-        # A node used to be offered whole — declared, then its lists, then its
-        # children — one sibling at a time. Which means an aggregate's attributes
-        # were offered before its later siblings existed, and an attribute that
-        # points at another aggregate could only resolve if that aggregate happened
-        # to be declared earlier in the file. Banking survives on luck: Customer is
-        # written above Account.
+        # Offering a node whole — declared, then its lists, then its children
+        # — one sibling at a time would mean an aggregate's attributes are
+        # offered before its later siblings exist, so an attribute that
+        # points at another aggregate could only resolve if that aggregate
+        # happens to be declared earlier in the file: banking would survive
+        # on luck, Customer written above Account.
         #
         # So siblings are declared in one pass and detailed in a second. It is the
         # same ordering the walk already used one level down — value objects before
@@ -256,7 +259,7 @@ module Hecks
         #
         #   the parent link   (plan.parent_key)   -> `parent_id`, the id
         #                     the walk already carries in from one level up
-        #   a walk-minted one (POSITION)           -> the walk index itself ;
+        #   a walk-minted one (`POSITION`)         -> the walk index itself ;
         #                     never a stored field (Member's own header:
         #                     "position is not a mint — it is read straight
         #                     out of the source file")
@@ -265,12 +268,12 @@ module Hecks
         #                     (Handler's own `event_type`, Dispatch's own
         #                     `command_name`)
         #
-        # `carried` still decides bare-vs-wrapped the normal way ; POSITION
+        # `carried` still decides bare-vs-wrapped the normal way ; `POSITION`
         # is the one case with no verb to ask `carried` about (`plan.
         # declare` is always nil for an entity-owned category — Plan#read's
         # own comment says why), so it is minted straight as a value object,
         # matching exactly what `declare`'s own field loop already mints a
-        # POSITION field as.
+        # `POSITION` field as.
         def node_identity(plan, category, node, index, parent_id)
           plan.identity_paths.each_with_object({}) do |path, fields|
             head = path.to_s.split(".").first
@@ -384,10 +387,11 @@ module Hecks
         # Where it sits among its siblings is a fact about the walk, not about the
         # node : a command does not know it is the third command on its aggregate.
         # The walk knows, so the walk supplies it, and every other field still
-        # comes from the node. Declaration order used to survive only because the
-        # meta store happened to iterate in insertion order — an accident that an
-        # ask ordered any other way would have taken away, and Reconstruction is
-        # the one reader that must have the source's order rather than a stable one.
+        # comes from the node. Without this, declaration order would survive only
+        # because the meta store happens to iterate in insertion order — an
+        # accident that an ask ordered any other way would take away, and
+        # Reconstruction is the one reader that must have the source's order
+        # rather than a stable one.
         # `private` above has no effect on a constant; kept here anyway,
         # beside the method that reads it, for the narrative.
         # rubocop:disable-next Lint/UselessConstantScoping
@@ -654,8 +658,8 @@ module Hecks
 
         # Command -> commands, ValueObject -> value_objects, Query -> queries.
         # Convention, not a table : the IR names a collection after what it holds.
-        # The pluraliser lives in Naming because there used to be two of them and
-        # one was wrong — see Naming.plural.
+        # The pluraliser lives in Naming, kept to exactly one implementation — a
+        # second one risks disagreeing with it — see Naming.plural.
         def collection_reader(category) = Naming.plural(Naming.snake(category))
       end
     end

data/lib/hecks/bluebook/meta_validator/plan.rb

@@ -3,11 +3,12 @@ module Hecks
     module MetaValidator
       # What the language says about itself, read back as something walkable.
       #
-      # The judge used to carry one hand-written branch per category, and the
-      # reason given for keeping it that way was that "which append command
-      # belongs to which list is not derivable from a name". True — and beside
-      # the point. It is derivable from the language's own IR, because every
-      # append command declares its target:
+      # ## Why a plan, not a hand-written branch per category
+      #
+      # "Which append command belongs to which list is not derivable from a
+      # name" sounds like a reason to hand-write one branch per category —
+      # and is beside the point. It is derivable from the language's own IR,
+      # because every append command declares its target:
       #
       #     command "Argument" do
       #       reference_to Command
@@ -24,7 +25,7 @@ module Hecks
       # Query / Entity, ValueObject -> Member, ProcessManager -> Handler ->
       # Dispatch all fall out of the declarations rather than being restated here.
       #
-      # Usage:
+      # ## Usage
       #
       #     plan = Plan.for(MetaValidator.grammar_registry)
       #     plan.category("Command").parent            # => "Aggregate"
@@ -52,6 +53,10 @@ module Hecks
           # Every verb this category declares, in declaration order. `alternates`
           # matters here: two commands can append to one list, and a verb missing
           # from this is a verb the coverage gate stops watching.
+          #
+          # @return [Array<String>] every command name this category declares
+          #   (the creating command, every setter, appender, alternate
+          #   appender, and sealer), `nil` entries dropped
           def verbs
             [declare, *setters.map(&:verb), *appends.values.map(&:verb),
              *alternates.map(&:verb), *sealers].compact
@@ -61,19 +66,35 @@ module Hecks
           # an id is a scalar — so the judge offers it bare, where every other
           # field goes as a one-field value object. The language answers this
           # about itself, so declaring a new reference needs no change here.
+          #
+          # @param verb [String] the command name declaring `argument`
+          # @param argument [String] the argument name to check
+          # @return [Boolean] whether `argument` on `verb` is a reference
           def references?(verb, argument)
             Array(references[verb.to_s]).include?(argument.to_s)
           end
 
+          # Reports whether this category is the root of the containment
+          # tree.
+          #
+          # @return [Boolean] whether this category has no parent — the root
+          #   of the containment tree
           def root? = parent.nil?
         end
 
+        # Reads the language's own self-description off `registry`.
+        #
+        # @param registry [Runtime::Registry] a registry with the language's
+        #   own "Bluebook" chapter already judged and assembled
+        # @return [Plan] the plan, built from that chapter's own aggregates
         def self.for(registry)
           new(registry.bluebook("Bluebook"))
         end
 
         attr_reader :categories
 
+        # @param meta [Bluebook::Chapter] the language's own assembled
+        #   "Bluebook" chapter
         def initialize(meta)
           @categories = {}
           meta.aggregates.each do |aggregate|
@@ -121,7 +142,17 @@ module Hecks
           @categories.freeze
         end
 
+        # Looks up one category by name.
+        #
+        # @param name [String, Symbol] the category name, such as
+        #   `"Command"` or `"ValueObject"`
+        # @return [Category, nil] the named category, or `nil` if the
+        #   language declares no such category
         def category(name) = @categories[name.to_s]
+
+        # Lists every category this plan holds.
+        #
+        # @return [Array<String>] every category name this plan holds
         def names          = @categories.keys
 
         # Every verb the language declares, spelled as the judge would
@@ -135,6 +166,10 @@ module Hecks
         # entity-owned category's own parent may itself be entity-
         # owned), so this stays what it already is: the judge's own
         # coverage promise, not a second guess at it.
+        #
+        # @return [Array<String>] every verb the language declares, dotted
+        #   and prefixed with `"Bluebook::"`, such as `"Bluebook::Aggregate.
+        #   Command.Argument"`
         def verbs
           @categories.flat_map do |name, category|
             category.verbs.map { |verb| "Bluebook::#{dotted_prefix(name)}.#{verb}" }
@@ -218,8 +253,8 @@ module Hecks
             # than restated. The judge has to know a record's id before it
             # dispatches, because the children it walks next carry it as their
             # parent — so it derives the same join the runtime will, off the same
-            # declaration. It used to be a branch per category, and a branch that
-            # disagreed with the runtime by one separator was a broken reference.
+            # declaration: a hand-written branch per category, disagreeing with
+            # the runtime by even one separator, would be a broken reference.
             identity_paths: aggregate.identity_paths,
             entity_owned:   entity_owned
           )

data/lib/hecks/bluebook/meta_validator/port_judge.rb

@@ -11,6 +11,7 @@ module Hecks
       class PortJudge
         attr_reader :refusals
 
+        # @param port [Bluebook::Port] the built port to judge
         def initialize(port)
           @port     = port
           @refusals = []

data/lib/hecks/bluebook/meta_validator/readings.rb

@@ -26,6 +26,13 @@ module Hecks
         # every one of them was a fact `Assembly::Contracts` is the right place to
         # keep: which shaper turns this list into rows. A list with no shaper reads
         # straight off the node, which is most of them.
+        #
+        # @param category [String] the node's own construct category, such
+        #   as `"Command"` or `"ValueObject"`
+        # @param list_name [String] the appendable list's own field name
+        # @param node [Object] the built IR node being judged
+        # @return [Array<Hash>] one row per element of `node`'s own
+        #   `list_name`, shaped by the category's own shaper if it has one
         def rows_for(category, list_name, node)
           shaper = Assembly.contract(category).shaper(list_name)
           return Array(node.public_send(list_name)) unless shaper
@@ -37,20 +44,39 @@ module Hecks
         # symbol argument as ":ceiling". Reading the object instead lost the colon,
         # and nothing downstream could tell an argument from a literal of the same
         # name.
+        #
+        # @param node [Object] the built IR node being judged (a `Query` or
+        #   `ReadModel`)
+        # @return [Array<Hash{Symbol => Object}>] each declared `where`
+        #   clause's own fields
         def where_rows(node) = Array(node.wheres).map(&:to_h)
 
         # The language holds a value object's name here ; the IR holds the object.
+        #
+        # @param node [Object] the built IR node being judged (an
+        #   `Aggregate`)
+        # @return [Array<Hash{Symbol => String}>] `{name: ...}` for every
+        #   declared value object
         def value_object_names(node) = node.value_objects.map { |shape| { name: shape.hecks_name } }
 
         # An identity is a list of parts, so it is offered one part at a time — the
         # same way attributes and transitions are. The IR holds the paths ; the
         # language holds a row per path, and the order between them is the whole
         # meaning, because the identity is their join.
+        #
+        # @param node [Object] the built IR node being judged (an
+        #   `Aggregate` or `Entity`)
+        # @return [Array<Hash{Symbol => String}>] `{value: ...}` for every
+        #   identity path part, in order
         def identity_rows(node) = node.identity_paths.map { |path| { value: path } }
 
         # Through to_h, which is where Bluebook.render_value spells a symbol argument as
         # ":source". The raw with_spec lost the colon, and a binding that reads an
         # argument became indistinguishable from one carrying a literal string.
+        #
+        # @param node [Object] the built IR node being judged (a `Dispatch`)
+        # @return [Array<Hash{Symbol => Object}>] `pair_rows`' own return
+        #   for `node`'s own `with_spec`
         def with_spec_rows(node) = pair_rows(node.to_h[:with_spec])
 
         # The same read, one level in — `compensates` folds `DispatchSpec`
@@ -59,19 +85,40 @@ module Hecks
         # "Dispatch"), so its own with_spec pairs live nested one hash
         # down from where `with_spec_rows` looks. `&.dig(...)` — no
         # compensation at all is not an error, it is `pair_rows(nil)`, empty.
+        #
+        # @param node [Object] the built IR node being judged (a `Dispatch`)
+        # @return [Array<Hash{Symbol => Object}>] `pair_rows`' own return
+        #   for `node`'s own `compensates.with_spec`, `[]` when `node` has
+        #   no compensation
         def compensates_with_spec_rows(node) = pair_rows(node.to_h[:compensates]&.dig(:with_spec))
 
         # A read model carries the same options an ask does, plus its filters — see
         # option_rows.
+        #
+        # @param node [Object] the built IR node being judged (a
+        #   `ReadModel`)
+        # @return [Array<Hash{Symbol => Object}>] `option_rows`' own return,
+        #   with filters included
         def read_model_option_rows(node) = option_rows(node, filters: true)
 
         # The canonical-form table is the expression grammar's, not this chapter's, so
         # the node is not consulted at all.
+        #
+        # @param _node [Object] unused; every node shares the one table
+        # @return [Array<Hash{Symbol => Object}>] `normalisation_rows`' own
+        #   return
         def normalisation_table(_node) = normalisation_rows
 
         # `lifecycle :status do transition "Retire" => "retired", from: ["issued", "active"] end`
         # is one declaration and two transitions. Offering it once would leave the
         # second unjudged, which is the whole failure this judge exists to avoid.
+        #
+        # @param node [Object] the built IR node being judged (an
+        #   `Aggregate` or `Entity`)
+        # @return [Array<Hash{Symbol => Object}>] `:command`, `:from_state`,
+        #   and `:to_state`, one row per declared `from` state (or one row
+        #   with a `nil` `:from_state` for an unconstrained transition);
+        #   `[]` if `node` declares no lifecycle
         def transition_rows(node)
           lifecycle = node.respond_to?(:lifecycle) ? node.lifecycle : nil
           return [] unless lifecycle
@@ -87,6 +134,10 @@ module Hecks
         # An open map — a member's fields, a dispatch's argument bindings — has no
         # value object that can hold it, so each entry becomes its own row. This is
         # why Member and Dispatch are roots in the language rather than lists.
+        #
+        # @param map [Hash, nil] the open map to flatten, or `nil`
+        # @return [Array<Hash{Symbol => Object}>] `{key:, value:}` for every
+        #   entry, `[]` when `map` is `nil`
         def pair_rows(map)
           Array(map&.to_h).map { |key, value| { key: key, value: value } }
         end
@@ -125,6 +176,14 @@ module Hecks
         #
         # Named `wheres`, `order_by` and `limit` so they gather back into exactly the
         # declaration keys the assembly already reads.
+        #
+        # @param node [Object] the built IR node being judged (a `Query` or
+        #   `ReadModel`)
+        # @param filters [Boolean] whether to also flatten `node`'s own
+        #   `wheres`/`order_by`/`limit`
+        # @return [Array<Hash{Symbol => Object}>] `[]` if `node` answers no
+        #   `extra_options_to_h`; otherwise `parts`' own rows for every
+        #   option `node` carries
         def option_rows(node, filters: false)
           return [] unless node.respond_to?(:extra_options_to_h)
 
@@ -139,6 +198,14 @@ module Hecks
           end
         end
 
+        # Reads a read model's own filtering fields, in the shape
+        # `option_rows` expects to flatten alongside its ordinary options.
+        #
+        # @param node [Object] the built IR node being judged (a
+        #   `ReadModel`)
+        # @return [Hash{Symbol => Object}] `:wheres` (`Array<Hash>`),
+        #   `:order_by`, and `:limit` (each `Hash` or absent), absent keys
+        #   dropped
         def filter_options(node)
           {
             wheres:   Array(node.wheres).map(&:to_h),
@@ -147,6 +214,17 @@ module Hecks
           }.reject { |_, held| held.nil? || held == [] }
         end
 
+        # Flattens one option's own value (or one element of a repeated
+        # option) into key/value rows.
+        #
+        # @param option [Symbol] the option's own name
+        # @param held [Object] the option's own value (a Hash-coercible
+        #   object) — one repetition's worth, for a repeated option
+        # @param at [Integer, nil] the repetition index, for a repeated
+        #   option; `nil` otherwise
+        # @return [Array<Hash{Symbol => String, Object}>] `:option`, `:key`,
+        #   `:value`, and `:at` (stringified, `nil` when `at` is `nil`), one
+        #   per key of `held`
         def parts(option, held, at)
           Hash(held).map do |key, value|
             { option: option.to_s, key: key.to_s, value: value, at: at&.to_s }
@@ -158,9 +236,14 @@ module Hecks
         # (`append: { name: :name, amount: :amount }`). So an append is offered
         # once per binding, and each one is judged.
         #
-        # The judge used to send `field: v(""), kind: v("argument"), source: v("")`
-        # here — three stubbed values, so every rule about what a mutation reads
-        # was being handed a blank and could never refuse.
+        # Sending `field: v(""), kind: v("argument"), source: v("")` here
+        # instead — three stubbed values — would hand every rule about what
+        # a mutation reads a blank, so it could never refuse.
+        #
+        # @param node [Object] the built IR node being judged (a `Command`)
+        # @return [Array<Hash{Symbol => Object}>] one row per binding for an
+        #   append/delegate/corrects mutation, or `set_row`'s own single-row
+        #   array for a set/increment/decrement
         def mutation_rows(node)
           Array(node.mutations).flat_map do |mutation|
             # `:delegate`/`:corrects` (CommandBuilder#delegates_to's and
@@ -185,6 +268,11 @@ module Hecks
 
         # A set/increment/decrement reads one thing: a command argument, or a
         # literal written into the bluebook.
+        #
+        # @param mutation [Bluebook::Mutation] a set/increment/decrement
+        #   mutation
+        # @return [Array(Hash{Symbol => Object})] a single-element array
+        #   holding `:target`, `:op`, `:field`, `:kind`, and `:source`
         def set_row(mutation)
           classified = mutation.to_h[:source] || {}
 
@@ -196,6 +284,10 @@ module Hecks
         # The normalisation table belongs to the expression grammar, not to any one
         # bluebook — it is how the canonical form of a rule is spelled. The language
         # models it because a bluebook's rules are canonicalised on the way in.
+        #
+        # @return [Array<Hash{Symbol => Object}>] one row per admitted
+        #   normalisation rule (`:strategy`, `:source_token`, `:replacement`,
+        #   `:boundary`, `:position`), `[]` if the table cannot be read
         def normalisation_rows
           table = Expression::CanonicalForm.table
           return [] unless table
@@ -217,10 +309,12 @@ module Hecks
 
         # What the bluebook calls a node, whichever kind of thing the node is.
         #
-        # This used to sniff — `respond_to?(:hecks_name) ? … : node.name` — because
-        # only value objects had crossed over. Every construct answers now, so
-        # there is nothing to choose between. It disappears entirely when the DSL
-        # stops handing the judge nodes at all.
+        # Every construct answers `hecks_name` now, so there is nothing to sniff
+        # (`respond_to?(:hecks_name) ? … : node.name`) or choose between. This
+        # disappears entirely when the DSL stops handing the judge nodes at all.
+        #
+        # @param node [Object] the built IR node being judged
+        # @return [String] the node's own declared name
         def declared_name(node) = node.hecks_name
 
         # One field of a Declare payload. Mostly a reader of the same name — the
@@ -233,6 +327,18 @@ module Hecks
         # `:parent` there ; a folded field names the object and member it lives in.
         # So the exceptions are looked up rather than repeated, and a new fold is one
         # line in one file instead of two lines in two.
+        #
+        # @param category [String] the node's own construct category, such
+        #   as `"Command"` or `"ValueObject"`
+        # @param node [Object] the built IR node being judged
+        # @param field [Symbol] the Declare payload field to read
+        # @param parent_id [String] the id the containment walk carries in
+        #   from one level up, offered when `field` is the parent pointer
+        # @return [Object] `field`'s own value: `node`'s declared name,
+        #   `parent_id`, a folded member's value (`through`), the read
+        #   model's own limit value, an encoded literal (`provenance`), or
+        #   `node.public_send(field)`; `nil` if `node` does not respond to
+        #   `field`
         def field_value(category, node, field, parent_id)
           return declared_name(node) if field == :name
 
@@ -271,6 +377,14 @@ module Hecks
         # member names are the ones the IR spells — a Lifecycle's `default`, an
         # OrderBy's `direction` — and reading the object raw is how a colon or a type
         # goes missing.
+        #
+        # @param node [Object] the built IR node being judged
+        # @param object [Symbol] the member object's own field name on
+        #   `node`, such as `:lifecycle`
+        # @param member [Symbol] the field to read off that object, such as
+        #   `:default`; `:transitions` returns the object itself
+        # @return [Object, nil] the member's own value, or `nil` if `node`
+        #   does not respond to `object` or that object is absent
         def through(node, object, member)
           held = node.respond_to?(object) ? node.public_send(object) : nil
           return nil unless held
@@ -281,6 +395,13 @@ module Hecks
         # What a setting command writes. A setter whose source is absent is not
         # dispatched at all — absent is not empty, and offering "" would turn every
         # "if you declare it, declare something" rule into "you must declare it".
+        #
+        # @param category [String] the node's own construct category
+        # @param node [Object] the built IR node being judged
+        # @param target [Symbol] the setter's own target field
+        # @return [Object, nil] the target's own value: the closed set's own
+        #   row count, a folded member's value (`through`), or
+        #   `node.public_send(target)`; `nil` if absent
         def setter_value(category, node, target)
           # `rows` folds into `closed_set` and `members` between them, with no single
           # member to name, so it keeps its own reading — see Contract#folded.
@@ -294,6 +415,11 @@ module Hecks
 
         # Only a declared closed set has a row count. An empty one is the defect,
         # so `rows` must stay absent rather than arrive as zero.
+        #
+        # @param node [Object] the built IR node being judged (a
+        #   `ValueObject`)
+        # @return [Integer, nil] the closed set's own row count, or `nil` if
+        #   `node` is not a declared closed set
         def closed_set_size(node)
           return nil unless node.respond_to?(:closed_set?) && node.closed_set?
 
@@ -305,6 +431,12 @@ module Hecks
         # that head's ID, and resolution does the rest. Encoding and decoding both
         # live here, because this is where the IR's shape differs from the
         # language's and nowhere else should know the spelling.
+        #
+        # @param row [Bluebook::Attribute] the attribute being offered
+        # @param aggregate_id [String] the owning head's own id, read for
+        #   its chapter prefix
+        # @return [String, nil] the target head's own id, or `nil` if `row`
+        #   is not a `reference_to` attribute
         def points_at(row, aggregate_id)
           return nil unless row.reference?
 
@@ -331,15 +463,33 @@ module Hecks
         #
         # nil stays nil rather than becoming "nil": absent is a real answer here,
         # and the language's own field is optional.
+        #
+        # @param value [Object] the value to encode: `nil`, `Symbol`,
+        #   `String`, `Hecks::StateRef`, `true`, `false`, `Integer`, `Float`,
+        #   `Hash`, or `Array` (recursively)
+        # @return [String, nil] the self-describing wire spelling, or `nil`
+        #   when `value` is `nil`
         def encode_literal(value) = value.nil? ? nil : Literal.render(value)
 
         # The way back out: an aggregate id becomes the type the IR spells. The
         # id is a join of chapter + name (Naming::IDENTITY_JOIN, the same join
         # `points_at` built it with, not the "::" a real bluebook's own type
         # names never carry) ; the wire format wants only the bare name.
+        #
+        # @param points_at_id [String] a target head's own id, as `points_at`
+        #   built it
+        # @return [String] `"Reference<Name>"`, the bare target name
         def reference_type(points_at_id) = "Reference<#{points_at_id.to_s.split(Naming::IDENTITY_JOIN).last}>"
 
         # One value out of a row, named by the value object's field.
+        #
+        # @param row [Hash, Object] the row to read: a Hash, an object
+        #   answering `field` directly, an object answering `to_h`, or a
+        #   bare scalar
+        # @param field [Symbol] the field name to read
+        # @return [Object] `row[field]` for a Hash, `row.public_send(field)`
+        #   when `row` answers `field` directly, `row.to_h[field]` for
+        #   anything else to_h-able, or `row` itself for a bare scalar
         def row_value(row, field)
           # A Hash first. Hash answers to `key` (Hash#key(value)) and to `value` on
           # some rows, so asking respond_to? before checking for a Hash reads a