hecks 1.3.0 → 1.4.0

data/lib/hecks/forms/html.rb

@@ -11,8 +11,14 @@ module Hecks
     # account number a support rep typed into a form and got wrong — flows
     # through here on every render, so escaping is not optional decoration.
     module Escape
+      # Escapes a value for HTML text content, replacing `&`, `<`, `>`, `"` and `'` with
+      # entities so nothing in it becomes a tag.
+      #
       # Order matters — `&` first, or every escape this method itself just
       # wrote (`&amp;`, `&lt;`, ...) gets re-escaped a second time.
+      #
+      # @param value [Object, nil] the value to show, rendered with `to_s`; nil renders as `""`
+      # @return [String] the escaped text
       def self.html(value)
         value.to_s
              .gsub("&", "&amp;")
@@ -22,14 +28,22 @@ module Hecks
              .gsub("'", "&#39;")
       end
 
+      # Escapes a value for use inside a quoted HTML attribute.
+      #
       # Safe inside a double-quoted HTML attribute specifically — `html`
       # already covers this (it escapes `"`), kept as a named alias so a
       # call site reads "this value fills an attribute" rather than repeating
       # the same escaping and leaving the reader to check they match.
+      #
+      # @param value [Object, nil] the attribute value, rendered with `to_s`; nil renders
+      #   as `""`
+      # @return [String] the escaped text, without surrounding quotes
       def self.attr(value) = html(value)
 
+      # Percent-encodes a value for use as a query-string value.
+      #
       # L12 (docs/audits/2026-08-10-main-bug-audit.md) — safe as a
-      # query-string VALUE. `html`/`attr` guard against the value becoming
+      # query-string value. `html`/`attr` guard against the value becoming
       # markup, but say nothing about it staying inside the URL syntax
       # position it was placed in: an aggregate's identity is free-form
       # unless its value object declares a `pattern:` (see S3 in the same
@@ -38,23 +52,32 @@ module Hecks
       # interpolation (a stray `&` smuggles a second query parameter, `#`
       # truncates the path at a fragment, `/` splits the path into an
       # extra segment, ...). Percent-encodes via
-      # `application/x-www-form-urlencoded` (`+` for space) — correct ONLY
+      # `application/x-www-form-urlencoded` (`+` for space) — correct only
       # for a query-string value (query_form_renderer.rb's `quick_links`,
-      # record_renderer.rb's `?to=`). For a URL PATH segment use `path`
+      # record_renderer.rb's `?to=`). For a URL path segment use `path`
       # below instead — `+` is a literal plus there, not an escaped space,
       # so this method would corrupt any id containing a space. Callers
-      # still wrap the ASSEMBLED href/Location in `attr` (or `html`) as
+      # still wrap the assembled href/Location in `attr` (or `html`) as
       # usual — this only covers the id's own component, not the
       # surrounding markup.
+      #
+      # @param value [Object, nil] the value to encode, rendered with `to_s`
+      # @return [String] the `application/x-www-form-urlencoded` form, a space rendered as `+`
       def self.url(value) = URI.encode_www_form_component(value.to_s)
 
-      # Same guard as `url`, for a URL PATH segment instead of a
+      # Percent-encodes a value for use as one URL path segment.
+      #
+      # Same guard as `url`, for a URL path segment instead of a
       # query-string value. `encode_www_form_component` renders space as
       # `+`, which is only meaningful inside a query string — in a path
       # segment `+` is a literal plus, so an id like "John Smith" would
       # round-trip to "John+Smith" and 404 against the real id "John
       # Smith". Reuse the same percent-encoding and just correct that one
       # character back to `%20`.
+      #
+      # @param value [Object, nil] the segment to encode, rendered with `to_s`
+      # @return [String] the percent-encoded segment, a space rendered as `%20` and `/` as
+      #   `%2F`
       def self.path(value) = URI.encode_www_form_component(value.to_s).gsub("+", "%20")
     end
 
@@ -64,6 +87,14 @@ module Hecks
     # `true` renders as a bare boolean attribute (`required`, not
     # `required="true"`); `nil`/`false` are dropped entirely.
     module Tag
+      # Renders a Hash of attributes as the text that sits inside an opening tag, escaping
+      # every value and spelling an underscored name with hyphens.
+      #
+      # @param pairs [Hash{Symbol => Object}] attribute values by name; `true`
+      #   renders the bare name, nil and `false` drop the attribute, anything else is
+      #   rendered with `to_s`
+      # @return [String] space-separated attributes, such as `required aria-describedby="x"`;
+      #   `""` when every pair is dropped
       def self.attrs(pairs)
         pairs.filter_map do |name, value|
           next if value.nil? || value == false
@@ -73,15 +104,28 @@ module Hecks
         end.join(" ")
       end
 
+      # Renders an opening tag with its attributes. The tag name is interpolated unescaped,
+      # so it must come from code, never from domain data.
+      #
+      # @param name [String] the element name, such as `"input"`
+      # @param pairs [Hash{Symbol => Object}] attributes, rendered as `attrs` renders them
+      # @return [String] the opening tag, such as `<input type="text" required>`
       def self.open(name, **pairs)
         rendered = attrs(pairs)
         rendered.empty? ? "<#{name}>" : "<#{name} #{rendered}>"
       end
 
-      # `self.open(...)`, not bare `open(...)` — this Html.open (an HTML tag
+      # Renders a void element such as `<input>`. A self-closing tag reads the same as an
+      # opening one; HTML5 needs no slash.
+      #
+      # `self.open(...)`, not bare `open(...)` — this `Tag.open` (an HTML tag
       # renderer, right above) shadows Kernel#open safely either way, but the
       # explicit receiver also settles Security/Open's static ambiguity.
-      def self.void(name, **pairs) = self.open(name, **pairs) # self-closing tags read the same; HTML5 needs no slash
+      #
+      # @param name [String] the element name, such as `"input"`
+      # @param pairs [Hash{Symbol => Object}] attributes, rendered as `attrs` renders them
+      # @return [String] the tag, identical to what `open` renders
+      def self.void(name, **pairs) = self.open(name, **pairs)
     end
   end
 end

data/lib/hecks/forms/index_renderer.rb

@@ -4,9 +4,15 @@ module Hecks
   module Forms
     # The home page: every exposed chapter, every aggregate on it — the
     # entry point into what would otherwise be a URL you'd have to already
-    # know. `chapters` is `{domain_name => Bluebook}`, in `expose` order
-    # (see config.rb).
+    # know. `chapters` is `{domain_name => Bluebook::Chapter}`, in `expose`
+    # order (see `Forms::Config` in forms.rb).
     module IndexRenderer
+      # Renders the home page body: one section per exposed chapter, each linking to its
+      # aggregates.
+      #
+      # @param chapters [Hash{String => Bluebook::Chapter}] the loaded chapters by domain
+      #   name, in `expose` order
+      # @return [String] the HTML page body; only the heading when `chapters` is empty
       def self.render(chapters)
         sections = chapters.map { |name, chapter| chapter_section(name, chapter) }
         <<~HTML
@@ -15,6 +21,12 @@ module Hecks
         HTML
       end
 
+      # Renders one chapter's section: its name, its vision as a badge when it declares one,
+      # and a link per aggregate showing how many commands and queries it has.
+      #
+      # @param name [String] the domain name, used as the heading and the first path segment
+      # @param chapter [Bluebook::Chapter] the loaded chapter
+      # @return [String] HTML for the section's heading and aggregate list
       def self.chapter_section(name, chapter)
         items = chapter.aggregates.map do |aggregate|
           counts = "#{aggregate.commands.size} command#{'s' unless aggregate.commands.size == 1}, " \

data/lib/hecks/forms/params.rb

@@ -4,35 +4,59 @@ require_relative "field_renderer"
 
 module Hecks
   module Forms
-    # The two directions between a flat, dotted, ALL-STRINGS web payload
+    # The two directions between a flat, dotted, all-strings web payload
     # (`{"amount.cents"=>"1050", "amount.currency"=>"USD"}`, whether it came
     # off a POST form body or a GET query string — Rack hands back the same
     # flat shape for both as long as nothing uses `[]` bracket names) and the
     # nested, typed hash `Dispatcher#dispatch`/`#query` actually take
     # (`{amount: {cents: 1050, currency: "USD"}}`).
     #
-    # `extract` NEEDS the Field tree, not just the raw params — a numeric
+    # `extract` needs the Field tree, not just the raw params — a numeric
     # leaf's own runtime check (`Value::Coercion#check_numeric_fields`)
     # requires an actual `Integer`/`Float`, not a String that merely looks
     # like one (`given.is_a?(expected)`, no coercion attempted there); a web
     # form can only ever hand back strings, so the cast has to happen here,
-    # once, using the SAME shape `FieldShape` already resolved for
+    # once, using the same shape `FieldShape` already resolved for
     # rendering the input in the first place — one reading of the IR, not
     # two that could disagree.
     module Params
-      # Every LEAF field carries its own full dotted path regardless of how
+      # Casts a flat, all-strings web payload into the nested, typed arguments a command or
+      # query takes, guided by the field tree the form was rendered from.
+      #
+      # Every leaf field carries its own full dotted path regardless of how
       # deep `FieldShape` nested it to get there — a single-attribute value
-      # object unwraps to a leaf sitting at the TOP of the fields array with
+      # object unwraps to a leaf sitting at the top of the fields array with
       # a two-segment path (`"reference.value"`), the exact same shape a
       # `:group`'s own child carries. So this collects every leaf as
-      # (full path -> value) FIRST, and nests by the path's OWN segments
+      # (full path -> value) first, and nests by the path's own segments
       # last — one nesting rule, blind to how a field arrived at its path.
+      #
+      # @param fields [Array<Forms::Field>] the resolved field tree the payload was posted
+      #   against
+      # @param raw [Hash{String => String}] the flat web payload, keyed by dotted field path
+      # @return [Hash{Symbol => Object}] nested, typed arguments keyed by path segment, ready
+      #   to splat into a dispatch; a blank optional field is left out
+      # @raise [ArgumentError] if a number field's text is not numeric, or two fields collide
+      #   at one path (see `nest`)
+      # @raise [TypeError] if a required number field is missing from `raw`
+      # @raise [JSON::ParserError] if a line of a list-of-value-objects field is not JSON
       def self.extract(fields, raw)
         pairs = {}
         fields.each { |field| collect(field, raw, pairs) }
         nest(pairs)
       end
 
+      # Gathers one field's typed value, and recursively its children's, into `pairs` under
+      # each leaf's full dotted path; a blank optional leaf adds nothing.
+      #
+      # @param field [Forms::Field] the field to read
+      # @param raw [Hash{String => String}] the flat web payload, keyed by dotted field path
+      # @param pairs [Hash{String => Object}] accumulator of typed values by dotted path,
+      #   added to in place
+      # @return [void]
+      # @raise [ArgumentError] if a number field's text is not numeric
+      # @raise [TypeError] if a required number field is missing from `raw`
+      # @raise [JSON::ParserError] if a line of a list-of-value-objects field is not JSON
       def self.collect(field, raw, pairs)
         case field.kind
         when :group, :money then field.children.each { |child| collect(child, raw, pairs) }
@@ -41,23 +65,32 @@ module Hecks
         end
       end
 
+      # Nests values keyed by dotted path into a Hash keyed by path segment, refusing two
+      # paths that cannot share one result.
+      #
       # A path-prefix collision: one field named (say) "price" alongside
-      # another named "price.cents" implies "price" is BOTH a scalar leaf
+      # another named "price.cents" implies "price" is both a scalar leaf
       # and the parent of a nested group — the two can never coexist in
       # the same result hash. Depending on which pair `each_with_object`
-      # reaches first, the naive walk below used to fail in one of two
-      # ways: a scalar planted first left `acc[segment] ||= {}` seeing a
-      # truthy non-Hash and reusing IT as `node`, so the next `node[leaf] =
-      # value` blew up with a raw `TypeError` from calling `String#[]=`
-      # with a Symbol key; a scalar planted AFTER the nested group instead
-      # sailed through `node[leaf] = value` and silently clobbered the
-      # entire nested hash with the scalar, losing every sibling under it
-      # with no error at all. Both directions are checked explicitly here
-      # so either order raises the SAME clear `ArgumentError` instead of a
-      # confusing crash or silent data loss — this is the family of error
-      # every command/query submission path in app.rb already rescues into
-      # a 422 (`ArgumentError` sits right alongside the domain refusals in
-      # every one of those rescue clauses).
+      # reaches first, an unguarded walk fails in one of two ways: a scalar
+      # planted first leaves `acc[segment] ||= {}` seeing a truthy non-Hash
+      # and reusing it as `node`, so the next `node[leaf] = value` blows up
+      # with a raw `TypeError` from calling `String#[]=` with a Symbol key;
+      # a scalar planted after the nested group instead sails through
+      # `node[leaf] = value` and silently clobbers the entire nested hash
+      # with the scalar, losing every sibling under it with no error at
+      # all. Both directions are checked explicitly here so either order
+      # raises the same clear `ArgumentError` instead of a confusing crash
+      # or silent data loss — this is the family of error every
+      # command/query submission path in app.rb already rescues into a 422
+      # (`ArgumentError` sits right alongside the domain refusals in every
+      # one of those rescue clauses).
+      #
+      # @param pairs [Hash{String => Object}] values keyed by dotted path, such as
+      #   `{"amount.cents" => 1050}`
+      # @return [Hash{Symbol => Object}] the nested result, such as `{amount: {cents: 1050}}`
+      # @raise [ArgumentError] if one path names a plain value where another names a nested
+      #   group, in either order
       def self.nest(pairs)
         pairs.each_with_object({}) do |(path, value), result|
           segments = path.to_s.split(".").map(&:to_sym)
@@ -74,6 +107,10 @@ module Hecks
         end
       end
 
+      # Builds, without raising, the error `nest` raises for a path-prefix collision.
+      #
+      # @param path [String] the dotted path at which the collision was found
+      # @return [ArgumentError] an error whose message names the conflicting path
       def self.nesting_collision(path)
         ArgumentError.new("#{path.inspect} conflicts with another field at the same path — " \
                           "one names it as a plain value and another as a nested group")
@@ -82,11 +119,21 @@ module Hecks
       SKIP = Object.new.freeze
       private_constant :SKIP
 
+      # Reads a `:list` field's textarea into an Array, one element per non-blank line.
+      #
       # One line of the textarea per element. A line that itself needs
       # several fields (a multi-attribute value object as a list element)
       # is read as JSON on that one line — the honest fallback documented in
       # docs/command-form-and-query-form-bluebook.md rather than a second
       # widget this prototype doesn't build yet.
+      #
+      # @param field [Forms::Field] a `:list` field whose first child describes one element
+      # @param raw [Hash{String => String}] the flat web payload, keyed by dotted field path
+      # @return [Array<Object>, Object] the elements — cast scalars for a leaf element,
+      #   symbol-keyed parsed JSON otherwise — or the private `SKIP` sentinel when the field
+      #   is absent or blank
+      # @raise [ArgumentError] if a number element's line is not numeric
+      # @raise [JSON::ParserError] if a non-leaf element's line is not JSON
       def self.extract_list(field, raw)
         text = raw[field.path]
         return SKIP if text.nil? || text.strip.empty?
@@ -97,6 +144,16 @@ module Hecks
         end
       end
 
+      # Reads one leaf field's typed value out of the payload; a boolean always answers, since
+      # an unticked checkbox is itself a value.
+      #
+      # @param field [Forms::Field] a leaf field
+      # @param raw [Hash{String => String}] the flat web payload, keyed by dotted field path
+      # @return [Boolean, Integer, Float, String, nil, Object] the cast value; nil when a
+      #   required non-number field is missing; the private `SKIP` sentinel when an optional
+      #   field is absent or empty
+      # @raise [ArgumentError] if a number field's text is not numeric
+      # @raise [TypeError] if a required number field is missing from `raw`
       def self.extract_leaf(field, raw)
         return checkbox(raw[field.path]) if field.kind == :boolean
 
@@ -106,10 +163,24 @@ module Hecks
         cast_scalar(field, text)
       end
 
+      # Reads a submitted checkbox value as a Boolean.
+      #
+      # @param raw_value [String, nil] the submitted text; nil when the field was not posted
+      # @return [Boolean] true for `"on"`, `"1"` or `"true"` in any letter case, false for
+      #   anything else
       def self.checkbox(raw_value)
         %w[on 1 true].include?(raw_value.to_s.downcase)
       end
 
+      # Casts a leaf's submitted text to the Ruby type the runtime's numeric check requires,
+      # which accepts an actual `Integer` or `Float` and never a numeric-looking String.
+      #
+      # @param field [Forms::Field] the leaf the text was submitted for
+      # @param text [String, nil] the submitted text
+      # @return [Integer, Float, String, nil] an Integer for a `:number` field with `step`
+      #   `"1"`, a Float for any other `:number` field, and `text` itself for every other kind
+      # @raise [ArgumentError] if a number field's text is not numeric
+      # @raise [TypeError] if a number field's text is nil
       def self.cast_scalar(field, text)
         case field.kind
         when :number then field.step == "1" ? Integer(text) : Float(text)
@@ -117,13 +188,23 @@ module Hecks
         end
       end
 
+      # Flattens held values back into the dotted-path, all-strings pairs a query string
+      # carries — the reverse of `extract`.
+      #
       # The other direction — a nested value hash back to the flat dotted
       # pairs a GET link's query string carries, so a query view's
-      # "shareable link" and its filter FORM stay two renderings of the
-      # SAME data rather than two formats that can drift. Reads with
+      # "shareable link" and its filter form stay two renderings of the
+      # same data rather than two formats that can drift. Reads with
       # `FieldRenderer.dig` — the identical full-path lookup a re-rendered
       # input's own value comes from — for the same reason `extract` above
       # nests by full path rather than by tree shape.
+      #
+      # @param fields [Array<Forms::Field>] the field tree naming which paths to read
+      # @param values [Hash{String, Symbol => Object}] held values, flat or nested; see
+      #   `FieldRenderer.dig`
+      # @param into [Hash{String => String}] accumulator the pairs are added to in place
+      # @return [Hash{String => String}] `into`, holding one pair per leaf with a non-nil value
+      #   and one per list (its elements newline-joined, `""` when it holds nothing)
       def self.flatten(fields, values, into: {})
         fields.each do |field|
           case field.kind
@@ -137,11 +218,19 @@ module Hecks
         into
       end
 
+      # Lists every dotted path a field tree submits under, whether or not anything was
+      # entered for it.
+      #
       # Every leaf/list path a field tree carries, independent of any
       # values — what `command_form_renderer.rb`'s inspect panel wants
       # ("which fields does this command take"), where `flatten` above wants
-      # "what does THIS submission look like" and returns nothing for a
+      # "what does this one submission look like" and returns nothing for a
       # field nothing was entered for.
+      #
+      # @param fields [Array<Forms::Field>] the field tree to walk
+      # @param into [Array<String>] accumulator the paths are appended to in place
+      # @return [Array<String>] `into`, holding each leaf and list path in render order;
+      #   `:group` and `:money` fields contribute their children's paths, not their own
       def self.paths(fields, into: [])
         fields.each do |field|
           case field.kind
@@ -152,6 +241,14 @@ module Hecks
         into
       end
 
+      # Renders held values as a URL query string, percent-encoding each flattened path and
+      # value.
+      #
+      # @param fields [Array<Forms::Field>] the field tree naming which paths to read
+      # @param values [Hash{String, Symbol => Object}] held values, flat or nested; see
+      #   `FieldRenderer.dig`
+      # @return [String] `key=value` pairs joined with `&`, without a leading `?`; `""` when
+      #   `flatten` yields no pairs
       def self.to_query_string(fields, values)
         pairs = flatten(fields, values)
         pairs.map { |key, value| "#{URI.encode_www_form_component(key)}=#{URI.encode_www_form_component(value)}" }.join("&")

data/lib/hecks/forms/port_argument.rb

@@ -5,13 +5,13 @@ module Hecks
     # boot. Two spellings the previous inline version got wrong:
     #
     #   --port=8080   the equals form — the old `ARGV.each_cons(2)` scan
-    #                 only ever recognized "--port", "8080" as TWO
+    #                 only ever recognized "--port", "8080" as two
     #                 separate argv entries, so this spelling matched
     #                 nothing and silently fell through to the default.
     #   -p abc        a non-numeric value — the old code did `.to_i` on
     #                 whatever followed unconditionally, so a typo
     #                 quietly became port 0 (Rackup/WEBrick's actual
-    #                 behavior for `Port: 0` is to bind an EPHEMERAL
+    #                 behavior for `Port: 0` is to bind an ephemeral
     #                 port — arguably useful on purpose elsewhere, but
     #                 never what a mistyped `-p abc` meant to ask for).
     #

data/lib/hecks/forms/query_form_renderer.rb

@@ -16,7 +16,7 @@ module Hecks
     # hiding that behind a form); a row of ready-made links for any
     # closed-set parameter, since a caller filtering by an enum should not
     # have to fill in a form to get a link they could just click; a filter
-    # FORM for everything else, which — being a GET form — produces
+    # form for everything else, which — being a GET form — produces
     # exactly the same kind of link on submit; and the results table once
     # a request actually supplies parameters.
     module QueryFormRenderer
@@ -60,7 +60,7 @@ module Hecks
 
       # The one enum-shaped parameter (if there is one) rendered as literal,
       # clickable links — no form to fill in for "show me the suspended
-      # ones". Capped at the FIRST closed-set field on purpose: a second one
+      # ones". Capped at the first closed-set field on purpose: a second one
       # would mean a cross product of links, which reads as noise rather
       # than help. A query with more than one is still fully reachable
       # through the filter form below.

data/lib/hecks/forms/record_renderer.rb

@@ -68,7 +68,7 @@ module Hecks
         end
       end
 
-      # Every non-creating command, EXCEPT a lifecycle transition that does
+      # Every non-creating command, except a lifecycle transition that does
       # not apply from the record's current state — the same rule
       # `Rules#admissible_transition` enforces at dispatch, read here so a
       # link that would only refuse is never offered in the first place.
@@ -78,7 +78,7 @@ module Hecks
 
         items = commands.map do |cmd|
           # L12 — the id is free-form (S3): percent-encoded as the query
-          # VALUE (a raw `&` here would smuggle a second bogus query
+          # value (a raw `&` here would smuggle a second bogus query
           # parameter), then the assembled href is attribute-escaped as
           # usual.
           href = "/#{domain}/#{aggregate.hecks_name}/#{cmd.hecks_name}.html?to=#{Escape.url(id)}"

data/lib/hecks/forms/record_table.rb

@@ -5,7 +5,7 @@ module Hecks
   module Forms
     # The one shape every renderer in this directory reads a record as —
     # `id` plus its state hash. `Runtime::Instance` already answers both,
-    # so `repository.all`'s own records pass straight through; a QUERY's
+    # so `repository.all`'s own records pass straight through; a query's
     # answer does not (`QueryInterpreter#call` flattens `{id:}.merge(state)`
     # into one hash with no method to call — see
     # docs/command-form-and-query-form-bluebook.md's note on why), so

data/lib/hecks/forms/value_object_shape.rb

@@ -1,11 +1,11 @@
 module Hecks
   module Forms
-    # THE VALUE-OBJECT CLASSIFICATION every consumer of a resolved VO
+    # The value-object classification every consumer of a resolved VO
     # shape needs, spelled once — `field_shape.rb` (a command's own
     # form), `ui_schema.rb` (embryonaut_console's table/detail-panel
     # renderer, a separate app, not this repo), and
     # `adapters/driven/sql_query_builder.rb` (a query's own ORDER BY/
-    # WHERE compiler) each grew their own copy of "is this VO money-
+    # where compiler) each grew their own copy of "is this VO money-
     # shaped," "does it have exactly one attribute, worth unwrapping,"
     # and "which member of it is numeric" — the same three questions,
     # answered identically by definition (a VO's shape doesn't change
@@ -22,7 +22,7 @@ module Hecks
         value_object.attributes.map { |a| a.name.to_s }.sort == %w[cents currency]
       end
 
-      # A VO with exactly one attribute is a NAME for a scalar, not a
+      # A VO with exactly one attribute is a name for a scalar, not a
       # genuine group (EmailAddress{address}, CustomerNumber{value}) —
       # [[feedback_name_the_scalar_field]]'s own reasoning, shared here
       # rather than re-decided per caller. Returns the sole attribute,

data/lib/hecks/forms.rb

@@ -2,7 +2,7 @@
 # `query_form.bluebook` will eventually become — see docs/
 # command-form-and-query-form-bluebook.md), the IR->HTML renderers, and
 # the Rack app that content-negotiates between them and a plain JSON
-# reading of the same dispatch. NOT required by `require "hecks"`
+# reading of the same dispatch. Not required by `require "hecks"`
 # itself — a project that never boots this file never pays for `rack`,
 # the same lazy-dependency discipline the Gemfile's own comment already
 # holds `pg`/`oauth2`/`aws-sdk-lambda` to.
@@ -19,7 +19,7 @@ module Hecks
   # `expose` deliberately does and does not cover.
   module Forms
     # `expose`'s own declaration — "which chapters does this app expose" —
-    # kept OUTSIDE the `Hecks.*` collector convention (`Hecks.bluebook`,
+    # kept outside the `Hecks.*` collector convention (`Hecks.bluebook`,
     # `Hecks.hecksagon`, ...) and outside `Runtime::Registry` entirely, on
     # purpose: a real language word goes through `syntax.bluebook` and
     # `MetaValidator` (see docs/implemented/guides/extending-hecks.md, "a new word is a
@@ -30,29 +30,49 @@ module Hecks
     # see docs/command-form-and-query-form-bluebook.md, "why this isn't
     # syntax.bluebook yet".
     #
-    # ONE `expose` GRANTS A WHOLE CHAPTER, not a command or a query
+    # One `expose` grants a whole chapter, not a command or a query
     # individually — the future `command_form.bluebook`/`query_form.bluebook`
-    # words are PER-DECLARATION (one command, one query, its own form/view,
+    # words are per-declaration (one command, one query, its own form/view,
     # possibly its own overrides), which `expose` doesn't do today and was
     # never trying to; it's the coarse "turn this chapter's forms on at
     # all" switch those finer words will eventually sit inside.
     class Config
       attr_reader :name, :exposes
 
+      # @param name [String, Symbol] the app name this configuration is registered under;
+      #   stored as a String
       def initialize(name)
         @name    = name.to_s
         @exposes = []
       end
 
+      # Switches on the forms of one whole chapter for this app; called inside the
+      # `Forms.configure` block.
+      #
+      # @param chapter_name [String, Symbol] name of the chapter (domain) to expose, such as
+      #   `"Banking"`; stored as a String
+      # @return [Array<String>] every chapter name exposed so far, in declaration order
       def expose(chapter_name) = @exposes << chapter_name.to_s
     end
 
+    # Declares an app and the chapters it exposes, replacing any earlier configuration
+    # registered under the same name.
+    #
+    # @param name [String, Symbol] the app name `App.for` later looks the configuration up by
+    # @yield evaluated with `instance_eval` against the new `Forms::Config`, so a bare
+    #   `expose "Banking"` inside the block reaches `Config#expose`; optional
+    # @return [Forms::Config] the configuration just registered
     def self.configure(name, &block)
       config = Config.new(name)
       config.instance_eval(&block) if block
       (@configs ||= {})[config.name] = config
     end
 
+    # Looks up the configuration an earlier `Forms.configure` registered.
+    #
+    # @param name [String, Symbol] the app name given to `Forms.configure`
+    # @return [Forms::Config, nil] the app's configuration, or nil when no app of that name
+    #   has been configured
     def self.config(name) = (@configs || {})[name.to_s]
   end
 end

data/lib/hecks/fqn.rb

@@ -16,7 +16,7 @@ module Hecks
       new(realm: realm, domain: domain, version: version, aggregate: aggregate, verb: query, kind: :query)
     end
 
-    # ONE ORDER-DEPENDENT PARSE PIPELINE: split -> shape-validate -> dispatch
+    # One order-dependent parse pipeline: split -> shape-validate -> dispatch
     # on segment count -> split domain/version -> classify kind -> cross-
     # field validate -> construct. Each step consumes locals (segments, verb,
     # kind) the step before it derived; splitting would mean threading all of

data/lib/hecks/framework/bluebook/governance.bluebook

@@ -2,6 +2,15 @@ Hecks.bluebook "Governance" do
   vision "Organizational authority is explicit, reviewable, and historically explainable."
   supporting
 
+  # WHAT THIS CHAPTER ANSWERS FOR EVERY DOMAIN THAT ATTACHES IT. The role
+  # check at dispatch, boot's refusal of an ungoverned `role`, the
+  # authorization adapter and the fuzzer's grant steering all read these
+  # three verbs from here, rather than recognising "Governance" by name.
+  provides "authorization",
+           assignments: "RoleAssignment.AssignmentsForActor",
+           grant:       "RoleAssignment.Assign",
+           transitions: "RoleTransition.Allowed"
+
   aggregate "RoleAssignment" do
     description "One actor holding one role, over one scope, from one point in time — revoked by setting when it ended, never deleted."