hecks 1.4.0 → 1.5.1

data/lib/hecks/bluebook/assembly/contract.rb

@@ -8,11 +8,11 @@ module Hecks
       # What a construct needs that the language cannot say, and how a claim that a
       # field needs no assembling is checked.
       #
-      # `derived:` used to be a list of names, and a list of names is a promise with
-      # nobody holding it. The coverage gate only asked whether a field was accounted
-      # for — so writing `derived: %i[version]` would have satisfied it while dropping
-      # a chapter's version in silence, which is the exact shape of every defect this
-      # arc has found. Naming a field derived is a claim, and a claim needs a kind:
+      # Naming a field derived is a claim, and a claim needs a kind, not just a name
+      # in a list. A bare list of names is a promise with nobody holding it: the
+      # coverage gate only asks whether a field is accounted for, so `derived:
+      # %i[version]` would satisfy it while dropping a chapter's version in
+      # silence — the exact shape of every defect this arc has found.
       #
       #   :parent            the containment tree supplies it — a `*_id`, or one of
       #                      the named pointers below. Checked against the name.
@@ -32,6 +32,10 @@ module Hecks
         # shape, because a list needs a reader per element and a folded field is
         # gathered rather than fetched. Same pattern as `rows`, in the other
         # direction: declare the exceptions, default the rest.
+        #
+        # @param key [String, Symbol] the field's declaration key, as `fields` names it
+        # @return [Symbol, Array, nil] the reader named in `reads` for `key`, or `nil`
+        #   when the field reads through the default single-cell reader
         def reader(key) = Hash(reads)[key.to_sym]
 
         # How an appendable list becomes rows the walk can offer. A list absent from
@@ -39,10 +43,24 @@ module Hecks
         # because the IR keeps a shape the language does not — a transition whose
         # `from` is a list is several rows, an append binds several fields at once,
         # an open map is one row per entry.
+        #
+        # @param list [String, Symbol] the appendable list's field name
+        # @return [Symbol, nil] the shaper method named in `rows` for `list`, or `nil`
+        #   when the list reads straight off the node instead
         def shaper(list) = Hash(rows)[list.to_sym]
 
+        # Whether `field` is one this contract accounts for, stored or derived.
+        #
+        # @param field [Symbol] the field name to check
+        # @return [Boolean] whether `field` is a key of `fields` or of `derived`
         def declares?(field) = fields.key?(field) || derived.key?(field)
 
+        # Names the kind of derived claim `field` makes, if any.
+        #
+        # @param field [Symbol] the derived field name to check
+        # @return [Symbol, Array, nil] the kind `derived` names for `field` — `:parent`,
+        #   `:children`, `:elsewhere`, `:walk`, an `[:computed, method]` or `[:folded,
+        #   object, member]` pair — or `nil` when `field` is not derived
         def kind_of(field) = derived[field]
 
         # The fields the walk supplies — every `derived: { field => :walk }` claim.
@@ -50,20 +68,27 @@ module Hecks
         # judge can order siblings, but no constructor takes one. This is the one
         # place that fact is stated ; `Specializer` and `Model::Deviations` read it
         # here rather than each keeping their own `%i[position]`.
+        #
+        # @return [Array<Symbol>] every field name whose derived kind is `:walk`
         def walked = derived.select { |_field, kind| kind == :walk }.keys
 
         # Where a folded field actually lives, as [object, member].
         #
         # `[:folded, :lifecycle, :field]` says the language's `state_field` is the
-        # `field` of the IR's one Lifecycle. That is the same fact `Readings` used to
-        # state a second time as `node.lifecycle&.field` — so saying it once here
-        # drives both directions: the walk reads the member on the way in, and the
-        # reconstruction gathers the members back into the object on the way out.
+        # `field` of the IR's one Lifecycle. `Readings` would otherwise have to state
+        # that fact a second time as `node.lifecycle&.field` — saying it once here
+        # drives both directions instead: the walk reads the member on the way in, and
+        # the reconstruction gathers the members back into the object on the way out.
         #
         # A nil member means the fold has no single member to name — `rows` is a
         # count of what `closed_set` and `members` hold between them, and `options`
         # spreads across eight keys. Those keep their own code, and the gate still
         # checks the object they name is real.
+        #
+        # @param field [Symbol] the derived field name to check
+        # @return [Array(Symbol, Symbol), Array(Array<Symbol>, nil), nil] the `[object,
+        #   member]` pair the field folds into — `member` is `nil` when the fold has
+        #   no single member to name — or `nil` when `field` does not fold at all
         def folded(field)
           kind = derived[field]
           return nil unless kind.is_a?(Array) && kind.first == :folded
@@ -81,6 +106,10 @@ module Hecks
         #
         # So a computed field is one the holder answers and the constructor does not
         # accept. `query_name` qualifies (`Naming.snake(name)`) ; `version` cannot.
+        #
+        # @param method [Symbol] the field name to check
+        # @return [Boolean] whether `holder` answers `method` but its constructor does
+        #   not accept it as a keyword
         def computes?(method)
           return false unless holder
           return false unless answers?(method)
@@ -88,10 +117,22 @@ module Hecks
           !accepts?(method)
         end
 
+        # Whether `holder` answers `method`, checked the way that fits how it is
+        # built: `respond_to?` for a `:declare` holder (a class, queried live) and
+        # `method_defined?` for a `:new` holder (an instance method, checked without
+        # building one).
+        #
+        # @param method [Symbol] the method name to check
+        # @return [Boolean] whether `holder` answers `method`
         def answers?(method)
           make == :declare ? holder.respond_to?(method) : holder.method_defined?(method)
         end
 
+        # Whether the holder's constructor takes `keyword` as a keyword argument.
+        #
+        # @param keyword [Symbol] the keyword to check
+        # @return [Boolean] whether the holder's constructor (`.declare` or
+        #   `#initialize`) accepts `keyword` as an optional or required keyword
         def accepts?(keyword)
           builder = make == :declare ? holder.method(:declare) : holder.instance_method(:initialize)
 
@@ -109,13 +150,18 @@ module Hecks
       #   owner                 Entity's own text twin of that link, which is why
       #                         Entity's contract claims `owner: :parent`
       #
-      # It used to read `%i[owner shape handler]` here while the model's copy read
-      # `owner aggregate bluebook`: `shape` and `handler` were Member's and
-      # Dispatch's parent fields before S17 (ADR 0026) made both nested entities,
-      # and nothing noticed the two lists had stopped agreeing. spec/assembly_spec
-      # now derives this set from `Plan` and the contracts and fails on any drift.
+      # `shape` and `handler` are not on this list — S17 (ADR 0026) made Member and
+      # Dispatch nested entities, so neither is a parent field any more the way
+      # `owner` is. `spec/assembly_spec` derives this set from `Plan` and the
+      # contracts directly and fails on any drift, rather than trusting this list to
+      # stay in sync with a second hand-written copy kept by the model generator.
       PARENT_POINTERS = %i[aggregate bluebook owner].freeze
 
+      # Whether `field` is a parent pointer that does not end in `_id`.
+      #
+      # @param field [String, Symbol] the field name to check
+      # @return [Boolean] whether `field` ends with `_id`, or is one of
+      #   `PARENT_POINTERS`
       def self.parent_pointer?(field)
         field.to_s.end_with?("_id") || PARENT_POINTERS.include?(field.to_sym)
       end
@@ -131,6 +177,12 @@ module Hecks
         Bluebook: %i[normalisations]
       }.freeze
 
+      # Whether `field` is allow-listed as describing something other than
+      # `category`'s own construct — see `ELSEWHERE`.
+      #
+      # @param category [String, Symbol] the construct category name
+      # @param field [Symbol] the field name to check
+      # @return [Boolean] whether `field` is on `category`'s `ELSEWHERE` entry
       def self.elsewhere?(category, field)
         Array(ELSEWHERE[category.to_sym]).include?(field)
       end

data/lib/hecks/bluebook/assembly/contracts.rb

@@ -24,18 +24,23 @@ module Hecks
       # about whether a declaration is admissible — the language settled that on the
       # way in. This is only how a spelling becomes an object again.
       #
-      # Why a table and not a method per category. The judge used to carry one
-      # hand-written branch per category, and the price was fourteen verbs the
-      # language declared and the walk never offered — every rule hanging off them
-      # decoration, and nothing red, because a branch that does not exist cannot
-      # fail. An assembler with a method per category is the same shape. So the
-      # table is checked against the language by spec/assembly_spec: a field the
-      # language declares that no contract consumes is a failure, not a silence.
+      # Why a table and not a method per category: a hand-written branch per
+      # category can decorate a verb the language declares without the walk ever
+      # offering it, and nothing goes red, because a branch that does not exist
+      # cannot fail. An assembler with a method per category is the same shape.
+      # The table avoids it because spec/assembly_spec checks it against the
+      # language: a field the language declares that no contract consumes is a
+      # failure, not a silence.
       #
       # The `derived` list is how a field says it needs no assembling — a parent
       # pointer the containment tree already knows, or something computed from what
       # is here (`query_name` is `Naming.snake(name)`, `creates?` is whether a verb
       # names a root). Naming one is a claim, and the coverage gate holds it.
+      #
+      # @param category [String, Symbol] the construct category name, such as
+      #   `"Aggregate"` or `:Command`
+      # @return [Bluebook::Assembly::Contract] the category's field contract
+      # @raise [KeyError] if no contract is registered for `category`
       def self.contract(category) = CONTRACTS.fetch(category.to_s)
 
       CONTRACTS = {
@@ -163,13 +168,13 @@ module Hecks
           fields: {
             name:          [:name,          :plain],
             description:   [:description,   :plain],
-            # A list of paths, exactly as an aggregate's is. The two used to differ
-            # — a Symbol here and a String there, which byte equality with `to_h`
-            # could not see because both render as a string, so the assembled graph
-            # got a String and `element_of` looked up `args["sequence"]` in a
-            # symbol-keyed payload and found nothing: "Reverse acts on one
-            # LedgerEntry — pass sequence:", while passing sequence. There is one
-            # spelling now, and no room left for that difference.
+            # A list of paths, exactly as an aggregate's is, with no room left for
+            # the two to differ. A Symbol here and a String there would look
+            # identical to `to_h`'s byte-equality check, since both render as a
+            # string, while diverging at runtime: the assembled graph would carry a
+            # String, and `element_of`'s lookup of `args["sequence"]` in a
+            # symbol-keyed payload would find nothing — refusing "Reverse acts on
+            # one LedgerEntry — pass sequence:" while sequence was in fact passed.
             identified_by: [:identified_by, :plain],
             attributes:    [:attributes,    [:each, :shape_field]],
             # ADR 0028 — the same shape Aggregate's own `preconditions`
@@ -263,11 +268,11 @@ module Hecks
         # S17, ADR 0026 — Dispatch is a genuine entity now, nested under
         # Handler (`entity "Dispatch"`, process_manager.bluebook) — two
         # levels deep, "no life outside its Handler" (the ADR's own
-        # words). `command_name` alone used to be Dispatch's own
-        # identity, until items #151/#152 (`process_manager.bluebook`'s
-        # own `DispatchPosition` comment) found it collided the instant a
-        # real handler fanned the same command out more than once —
-        # `position` now joins it, walk-minted the same way every other
+        # words). `command_name` alone is not Dispatch's own identity —
+        # items #151/#152 (`process_manager.bluebook`'s own
+        # `DispatchPosition` comment) found it collides the instant a
+        # real handler fans the same command out more than once, so
+        # `position` joins it, walk-minted the same way every other
         # category's own `position` is (`derived: { position: :walk }`,
         # the same entry ProcessManager's own contract carries above) —
         # never a stored field on `DispatchSpec` itself, exactly like

data/lib/hecks/bluebook/assembly/marks.rb

@@ -9,7 +9,7 @@ module Hecks
       # is that Shapes rebuilds hashes and this rebuilds objects, so it has to
       # recover types rather than just strings.
       #
-      # Encoding losses are the LARGEST family of bug in this codebase, and every
+      # Encoding losses are the largest family of bug in this codebase, and every
       # member has the same shape: reading an object where `to_h` holds a spelling.
       # So each method below names the spelling it inverts.
       module Marks
@@ -18,6 +18,14 @@ module Hecks
         # `Attribute#to_h` spells a type with `to_s`, so a reference arrives as
         # "Reference<Customer>" and has to become an edge again. Everything else is
         # a name and stays one.
+        #
+        # @param field [Hash{Symbol => Object}] one attribute's declared row, keyed
+        #   `:type` (String, a plain type name or `"Reference<Target>"`), `:name`
+        #   (String), `:list` and `:optional` (read as truthy), `:default` (Object,
+        #   nil), `:pattern` (String, nil), `:admits` (String, nil) and
+        #   `:relationship` (String, nil), each the raw declared value
+        # @return [Bluebook::Attribute] the attribute, with `type` resolved to a
+        #   `Bluebook::Reference` when the row spelled one
         def attribute(field)
           type = field[:type].to_s
           target = type[/\AReference<(.+)>\z/, 1]
@@ -50,11 +58,18 @@ module Hecks
         # The same shape. Two names because a head's field and a verb's argument are
         # different things in the language even though the IR keeps one class for
         # both — `Aggregate.Attribute` and `Command.Argument` are separate verbs.
+        #
+        # @param field [Hash{Symbol => Object}] see `attribute`
+        # @return [Bluebook::Attribute] see `attribute`
         def shape_field(field) = attribute(field)
 
         # One part of an identity. It goes in as a row so the language can hold an
         # ordered list of them, and comes back out as the path it always was —
         # a String, because `identity_paths` splits paths and never symbols.
+        #
+        # @param part [Hash{Symbol => Object}] one identity-path row, keyed `:value`
+        #   (Object, read via `to_s`)
+        # @return [String] the path segment
         def identity_path(part) = part[:value].to_s
 
         # A member's fields — an open map, which is why Member is its own root in
@@ -64,6 +79,11 @@ module Hecks
         # and the language stores them as text: `member code: "JPY", minor_units: 0`
         # came back with a minor_units of "0", and a closed set that admits the string
         # would refuse the number the caller passes.
+        #
+        # @param pairs [Array<Array(String, Object)>] one member's own field pairs,
+        #   each `[field_name, raw_value]` as declared
+        # @return [Hash{Symbol => Object}] the member's fields, keyed by field name,
+        #   each value read back to its native type through `unmark_scalar`
         def member(pairs)
           pairs.to_h { |key, value| [key.to_sym, unmark_scalar(value)] }
         end
@@ -71,6 +91,12 @@ module Hecks
         # A read model's gathered head. The keys must be symbols whichever way the
         # declaration arrived, and `as` must be one too: it names the reader the
         # projection answers to, and `ReadModel#to_h` spells it `to_s`.
+        #
+        # @param row [Hash{Symbol => Object}] one aggregate-head row, keyed
+        #   `:aggregate` (String), `:as` (String, the reader name) and `:many`
+        #   (Boolean)
+        # @return [Hash{Symbol => Object}] the head, with every key a Symbol and
+        #   `:as` read back to a Symbol
         def head(row)
           row.to_h { |key, value| [key.to_sym, key.to_sym == :as ? value.to_sym : value] }
         end
@@ -78,12 +104,20 @@ module Hecks
         # A group_by field's own name — the builder's native shape is already
         # `{field: :symbol}`, so this matches it rather than leaving `field`
         # as the String `Shapes#group_by_field` reads back.
+        #
+        # @param row [Hash{Symbol => String}] one group-by row, keyed `:field`
+        # @return [Hash{field: Symbol}] the row with `:field` read back to a Symbol
         def group_by_field(row) = { field: row[:field].to_sym }
 
         # A scalar that was written as itself rather than inspected — a member's
         # value, where the language holds text and the type has to be read back from
         # the shape of it. Unlike `read`, a bare word stays a String here, because
         # a closed set admits words far more often than symbols.
+        #
+        # @param value [Object] the raw declared scalar, read via `to_s`
+        # @return [true, false, Integer, Float, String] `true`/`false` for those
+        #   literal words, a number when the text matches a bare integer or decimal
+        #   pattern, or the string itself otherwise
         def unmark_scalar(value)
           text = value.to_s
           return true       if text == "true"
@@ -97,12 +131,32 @@ module Hecks
         # A saga's argument bindings. Each value rides Literal's spelling, which
         # marks a Symbol with a leading colon — lose it and an argument reads as a
         # string of the same name.
+        #
+        # @param with [Array<Array(String, String)>, nil] the declared bindings,
+        #   each `[argument_name, literal_spelling]` pair, or `nil` for none
+        # @return [Hash{Symbol => Object}] the bindings, keyed by argument name,
+        #   each value read back through `Literal.read`
         def bindings(with) = Array(with).to_h { |key, value| [key.to_sym, read(value)] }
 
+        # Builds one aggregate or value object invariant from its declared row.
+        #
+        # @param rule [Hash{Symbol => String}] one invariant's declared row, keyed
+        #   `:description` and `:canonical` (the canonical-form rendering of the
+        #   rule's expression)
+        # @return [Bluebook::Invariant] the invariant, with `predicate`/`ast` left
+        #   `nil` — `Expression::Evaluator` parses `canonical` on demand when
+        #   neither is set
         def invariant(rule)
           Invariant.new(description: rule[:description], canonical: rule[:canonical])
         end
 
+        # Builds one command precondition from its declared row.
+        #
+        # @param rule [Hash{Symbol => String}] one given's declared row, keyed
+        #   `:description` and `:canonical` (the canonical-form rendering of the
+        #   rule's expression)
+        # @return [Bluebook::Given] the given, with `predicate`/`ast` left `nil` —
+        #   `Expression::Evaluator` parses `canonical` on demand when neither is set
         def given(rule)
           Given.new(description: rule[:description], canonical: rule[:canonical])
         end
@@ -111,6 +165,11 @@ module Hecks
         # All three fields are identifiers, unlike Invariant/Given's own
         # free text, so — like `attribute`'s own `name`/`type` below —
         # they come back as Symbols.
+        #
+        # @param row [Hash{Symbol => String}] one projected-field's declared row,
+        #   keyed `:name`, `:reference` and `:remote_field` (each an identifier)
+        # @return [Bluebook::ProjectedField] the projected field, with each
+        #   identifier read back to a Symbol
         def projected_field(row)
           ProjectedField.new(name: row[:name].to_sym, reference: row[:reference].to_sym,
                              remote_field: row[:remote_field].to_sym)
@@ -122,6 +181,14 @@ module Hecks
         # Symbol, wearing its colon) or a literal — the distinction that is the
         # whole reason `append: { direction: "out" }` was once indistinguishable
         # from an argument named `out`.
+        #
+        # @param change [Hash{Symbol => Object}] one mutation's declared row, keyed
+        #   `:target` (String), `:op` (String, such as `"set"`, `"append"`,
+        #   `"delegate"` or `"corrects"`), `:fields` (Array, for the append-shaped
+        #   ops) and `:source` (Hash, for any other op)
+        # @return [Bluebook::Mutation] the mutation, with `source` a
+        #   `Hash{Symbol => Object}` of field bindings for an append-shaped op, or
+        #   `classified`'s own result for any other
         def mutation(change)
           target = change[:target].to_sym
           op     = change[:op].to_sym
@@ -135,12 +202,27 @@ module Hecks
           Mutation.new(target: target, op: op, source: classified(change[:source]))
         end
 
+        # Reads an append mutation's field bindings back off their declared rows.
+        #
+        # @param fields [Array<Array(String, String)>, nil] the append's declared
+        #   field bindings, each `[field_name, literal_spelling]` pair, or `nil`
+        #   for none
+        # @return [Hash{Symbol => Object}] the bindings, keyed by field name, each
+        #   value read back through `Literal.read`
         def appended(fields)
           Array(fields).to_h { |field, source| [field.to_sym, read(source)] }
         end
 
         # A set reads one thing, and `classified_source` said which: an argument by
         # name, or a literal by value.
+        #
+        # @param source [Hash{Symbol => Object}, nil] the mutation's declared
+        #   source, keyed `:kind` (String, `"argument"`, `"state"` or a literal
+        #   kind) plus `:name` (String, for `"argument"`/`"state"`) or `:value`
+        #   (Object, for a literal), or `nil` for no source
+        # @return [Symbol, Hecks::StateRef, Object, nil] the command argument name,
+        #   a state self-reference, the literal value, or `nil` when `source` is
+        #   `nil`
         def classified(source)
           return nil if source.nil?
 
@@ -155,19 +237,22 @@ module Hecks
         #
         # A where-clause value, a saga's argument bindings, an append binding, a
         # limit: all of them ride Literal's self-describing form, so all of them
-        # come back through here. There were two readers (`read` and `unmark`)
-        # that disagreed about quoted strings and numbers, and which one a call
-        # site got was a coin toss the comments had to keep apologising for.
-        #
-        # An object literal is the one that bit. A saga leg binds `narrative: {
-        # text: "transfer out" }` — a value object's fields written inline — and
-        # `to_s` on a Hash used to be its inspect form, so it came back as text.
-        # Read as a string it reached the runtime as `"{:text=>\"transfer out\"}"`,
-        # coercion refused it, the debit leg was never delivered, and the whole
-        # settlement wire stopped: banking emitted TransferRequested five times and
-        # TransferDebited never. A whole-history replay gate caught what every other
-        # gate missed, because a saga that silently does nothing looks exactly like
-        # a saga with nothing to do.
+        # come back through this one reader, never a second one that might
+        # disagree about a quoted string or a number.
+        #
+        # An object literal is the one that bites hardest. A saga leg binds
+        # `narrative: { text: "transfer out" }` — a value object's fields written
+        # inline — and reading it as a plain string rather than through `Literal`
+        # would reach the runtime as `"{:text=>\"transfer out\"}"`, which coercion
+        # refuses: the debit leg is never delivered, and the whole settlement wire
+        # stops — banking emits TransferRequested five times and TransferDebited
+        # never. A whole-history replay gate is what catches this, because a saga
+        # that silently does nothing looks exactly like a saga with nothing to do.
+        #
+        # @param value [String, Object] wire spelling produced by `Literal.render`,
+        #   or a bare word
+        # @return [nil, true, false, Integer, Float, Symbol, Hecks::StateRef,
+        #   String, Hash, Array] the value read back — see `Literal.read`
         def read(value) = Literal.read(value)
 
         # `target:` (ADR 0055) — read straight off the wire, unconverted:
@@ -180,12 +265,25 @@ module Hecks
         # declared `on:` — `clause[:target]`/`declared[:target]` reads
         # `nil` for a missing key exactly like an explicit `nil` would,
         # so this is additive, not a migration.
+        #
+        # @param clause [Hash{Symbol => Object}] one where-clause's declared row,
+        #   keyed `:field` (String), `:op` (String, a comparator name), `:value`
+        #   (String, Literal's spelling) and `:target` (String, `nil` when absent)
+        # @return [QuerySpecification::Common::WhereClause] the clause, with `op`
+        #   read to a Symbol and `value` read back through `Literal.read`
         def where_clause(clause)
           QuerySpecification::Common::WhereClause.new(
             field: clause[:field], op: clause[:op].to_sym, value: read(clause[:value]), target: clause[:target]
           )
         end
 
+        # Builds a query's declared ordering, if it declares one.
+        #
+        # @param declared [Hash{Symbol => Object}, nil] the declared order-by row,
+        #   keyed `:field` (String), `:direction` (String) and `:target` (String,
+        #   `nil` when absent), or `nil` when the construct declares no ordering
+        # @return [QuerySpecification::Common::OrderBy, nil] the order-by, with
+        #   `direction` read to a Symbol, or `nil` when `declared` is `nil`
         def order_by(declared)
           return nil unless declared
 
@@ -194,6 +292,14 @@ module Hecks
           )
         end
 
+        # Builds a query's declared limit, if it declares one.
+        #
+        # @param declared [Hash{Symbol => Object}, nil] the declared limit row,
+        #   keyed `:value` (String, Literal's spelling) and `:target` (String,
+        #   `nil` when absent), or `nil` when the construct declares no limit
+        # @return [QuerySpecification::Common::LimitSpec, nil] the limit, with
+        #   `value` read back through `Literal.read`, or `nil` when `declared` is
+        #   `nil`
         def limit(declared)
           return nil unless declared
 
@@ -219,6 +325,20 @@ module Hecks
         # with `to_s`, so the colon is not there to strip.
         SYMBOLIC = %i[mode policy tenant].freeze
 
+        # Builds one query specification option from its declared row and `OPTIONS`.
+        #
+        # @param name [Symbol] the option's name, a key of `OPTIONS` (`:offset`,
+        #   `:cursor`, `:null_semantics`, `:authorization` or `:inspection`)
+        # @param declared [Hash{Symbol => Object}, nil] the option's declared row,
+        #   or `nil` when the construct does not declare this option
+        # @return [QuerySpecification::Common::OffsetSpec,
+        #   QuerySpecification::Common::CursorSpec,
+        #   QuerySpecification::Common::NullSemantics,
+        #   QuerySpecification::Common::AuthorizationSpec,
+        #   QuerySpecification::Common::InspectionSpec, nil] the option built
+        #   through the holder `OPTIONS` names for `name`, or `nil` when `declared`
+        #   is `nil`
+        # @raise [KeyError] if `name` is not a key of `OPTIONS`
         def option(name, declared)
           return nil if declared.nil?
 
@@ -226,6 +346,15 @@ module Hecks
           holder.new(**Hash(declared).to_h { |key, value| [key, option_value(key, value, marked)] })
         end
 
+        # Reads one option member's declared value back to its native type.
+        #
+        # @param key [Symbol] the option member's name being read
+        # @param value [Object, nil] the declared value for that member
+        # @param marked [Array<Symbol>] the members of this option that ride
+        #   Literal's spelling, from `OPTIONS`
+        # @return [Object, nil] `value` read back through `Literal.read` when
+        #   `key` is marked, a Symbol when `key` is one of `SYMBOLIC`, the raw
+        #   `value` otherwise, or `nil` when `value` is `nil`
         def option_value(key, value, marked)
           return nil               if value.nil?
           return read(value)       if marked.include?(key)

data/lib/hecks/bluebook/assembly/specializer.rb

@@ -27,10 +27,23 @@ module Hecks
         # (searched recursively, the same reason `Value::Coercion#find_
         # entity` does: a nested entity, like `Dispatch` inside
         # `Handler`, is not a direct child of any aggregate either).
+        #
+        # @param chapter [Bluebook::Chapter] the chapter to search
+        # @param name [String, Symbol] the construct's declared name
+        # @return [Bluebook::Aggregate, Class, nil] the aggregate, or the entity class
+        #   (a `Bluebook::Entity` subclass) nested anywhere under one, or `nil` if
+        #   `chapter` declares no construct by that name
         def construct_for(chapter, name)
           chapter.aggregate(name) || chapter.aggregates.filter_map { |a| find_entity(a, name) }.first
         end
 
+        # Searches a construct's own entities, recursively, for one by name.
+        #
+        # @param construct [Bluebook::Aggregate, Class] the aggregate, or entity class,
+        #   to search under
+        # @param name [String, Symbol] the entity's declared name
+        # @return [Class, nil] the entity class (a `Bluebook::Entity` subclass), or `nil`
+        #   if none of `construct`'s nested entities has that name
         def find_entity(construct, name)
           construct.entities.each do |candidate|
             return candidate if candidate.hecks_name == name
@@ -52,6 +65,12 @@ module Hecks
         # So the skip reads the category's own walk claims (`Contract#walked`)
         # rather than restating `position` here — Handler, which has no
         # walk-minted position, skips nothing.
+        #
+        # @param category [String, Symbol] the construct category's name, such as
+        #   `"Aggregate"` or `"Command"`
+        # @return [Hash{Symbol => Array(Symbol, Symbol)}] a `contracts.rb`-shaped
+        #   `fields:` table, one `field => [field, :plain]` entry per scalar,
+        #   non-reference, non-walked attribute the language declares for `category`
         def fields_for(category)
           language = construct_for(MetaValidator.grammar_registry.bluebook("Bluebook"), category.to_s)
           walked   = Assembly.contract(category).walked

data/lib/hecks/bluebook/assembly.rb

@@ -8,6 +8,8 @@ module Hecks
     # into the graph the runtime runs: IR aggregates with their verbs, value
     # objects, entities and asks, owned by the chapter that declares them.
     #
+    # ## Why a hash, not a runtime
+    #
     # It takes a hash, not a runtime, on purpose. That makes it a pure inverse of
     # `to_h` and testable without the meta-domain in the picture at all:
     #
@@ -17,23 +19,39 @@ module Hecks
     # Feed it the reconstruction instead and the same code assembles what the
     # language holds — the only difference being where the declarations came from.
     #
+    # ## One table, not a method per category
+    #
     # Every field is read from one table. There is no method per category here:
     # `Contracts` names what the language cannot say about a construct, `Build`
-    # reads it, and the coverage gate holds the table to the language. The first
-    # draft of this file did have a method each, which is the shape the judge used
-    # to have — and the price of that shape was fourteen verbs the language declared
-    # and nothing ever offered.
+    # reads it, and the coverage gate holds the table to the language. A method
+    # per category can decorate a verb the language declares without ever
+    # offering it; the table cannot, because `spec/assembly_spec` checks every
+    # field the language declares against it.
+    #
+    # ## What stays hand-written
     #
-    # What stays hand-written is the containment: which construct holds which.
-    # That is not a field table. (The runtime surface is no longer built here at
-    # all — the door is a per-boot projection, facade/surface.rb.)
+    # The containment — which construct holds which — stays hand-written; it is
+    # not a field table. The runtime surface is no longer built here at all — the
+    # door is a per-boot projection, facade/surface.rb.
     class Assembly
+      # Builds the graph the runtime runs from one chapter's declared hash.
+      #
+      # @param declaration [Hash{Symbol => Object}] a chapter's declarations, in the
+      #   shape `Chapter#to_h` spells
+      # @return [Bluebook::Chapter] the assembled chapter, with its aggregates, read
+      #   models and process managers built and wired
       def self.call(declaration) = new(declaration).bluebook
 
+      # @param declaration [Hash{Symbol => Object}] a chapter's declarations, in the
+      #   shape `Chapter#to_h` spells
       def initialize(declaration)
         @declaration = declaration
       end
 
+      # Assembles this instance's declared hash into the chapter's runtime graph.
+      #
+      # @return [Bluebook::Chapter] the assembled chapter, with its aggregates, read
+      #   models and process managers built and wired
       def bluebook
         aggregates = Array(@declaration[:aggregates]).map { |row| AggregateAssembly.new(row).aggregate }
         models     = Array(@declaration[:read_models]).map { |row| Build.call("ReadModel", row) }