hecks 1.4.0 → 1.5.1

data/lib/hecks/facade/handle.rb

@@ -1,4 +1,6 @@
 require_relative "../naming"
+require_relative "../runtime/caller"
+require_relative "../ports/authorization"
 
 module Hecks
   module Facade
@@ -41,7 +43,7 @@ module Hecks
       # @param key [Symbol, String] the attribute name
       # @return [Object, nil] the value held in state (a scalar, a value object, a list,
       #   or a referenced record's id); `nil` when the field is unset or not in state
-      def [](key) = @state[key.to_sym]
+      def [](key) = redacted(key.to_sym)
 
       # Answers the record's state as a plain Hash with the bare identity under `:id`.
       #
@@ -59,7 +61,7 @@ module Hecks
       #
       # @return [Hash{Symbol => Object}] a new Hash of every state field by attribute
       #   name, plus `:id` holding the identity String
-      def to_h = @state.merge(id: @id)
+      def to_h = @state.to_h { |key, _| [key, redacted(key)] }.merge(id: @id)
 
       # Names the aggregate this record belongs to, in the form every dispatch verb and
       # event is addressed by.
@@ -120,7 +122,7 @@ module Hecks
       #   written yet
       # @raise [NoMethodError] if `name` is neither a key in state nor a declared field
       def method_missing(name, *args, **kwargs, &)
-        return @state[name] if @state.key?(name) || reader?(name)
+        return redacted(name) if @state.key?(name) || reader?(name)
 
         super
       end
@@ -133,6 +135,77 @@ module Hecks
 
       def repository = @dispatcher.registry.repository(@domain, @ir)
 
+      # One field's value, with any Privacy::Marking-flagged leaf masked
+      # out unless the ambient caller holds a live Governance grant of
+      # the marking's own `readable_by` — the read-side half of the
+      # Privacy framework member (lib/hecks/framework/bluebook/
+      # privacy.bluebook): a marking's presence is what makes a read
+      # redacted, not a separate flag this class carries itself.
+      #
+      # ALWAYS THE STRONG CHECK, never the weak string-only fallback
+      # `CommandRules::Authorization#refuse_role_mismatch` allows an
+      # unidentified caller — a read gate gone wrong is a leak, not a
+      # refused command, so an ambient caller with no `actor_id` (or no
+      # caller at all) is masked here, full stop, rather than waved
+      # through the way a self-asserted `role` string is for a command.
+      #
+      # ONE LEVEL OF NESTING ONLY — `attendee.medications` masks inside
+      # the returned `Runtime::Value` via its own `#with`; a marking two
+      # levels deep is not supported and is left unmasked rather than
+      # silently mishandled, since nothing in this corpus needs it yet.
+      #
+      # @param field [Symbol] the state key being read
+      # @return [Object, nil] `@state[field]`, or a copy with the marked leaf replaced by
+      #   the literal String `"[redacted]"` when the caller is not authorized to see it
+      def redacted(field)
+        raw = @state[field]
+        rows = marked_paths.select { |row| row[:attribute_path][:value].to_s.split(".", 2).first == field.to_s }
+        return raw if rows.empty?
+
+        rows.each do |row|
+          path = row[:attribute_path][:value].to_s
+          next if authorized_for?(row[:readable_by][:value].to_s)
+
+          segments = path.split(".", 2)
+          if segments.size == 1
+            raw = "[redacted]"
+          elsif raw.is_a?(Runtime::Value)
+            raw = raw.with(segments[1], "[redacted]")
+          end
+        end
+
+        raw
+      end
+
+      # Every Privacy::Marking declared for this record's own aggregate — `[]` when the
+      # Privacy framework member is not attached in this boot at all, checked once and
+      # cheaply rather than paying for a query dispatch every read on a domain that never
+      # attached Privacy.
+      #
+      # @return [Array<Hash>] `Privacy::Marking.ForDomain`'s own rows for this `fqn`
+      def marked_paths
+        return @marked_paths if defined?(@marked_paths)
+        return @marked_paths = [] unless @dispatcher.registry.bluebook("Privacy")
+
+        @marked_paths = @dispatcher.query("Privacy::Marking.ForDomain", domain: fqn)
+      end
+
+      # Whether the ambient caller holds a live Governance grant of `role`, over this
+      # record's own domain — `false` outright for an unidentified caller or a domain
+      # with no authorization provider attached, never the weak fallback a command's own
+      # role check allows (see `redacted`'s own header for why).
+      #
+      # @param role [String] the marking's own `readable_by`
+      # @return [Boolean] true only for an identified caller holding a live grant
+      def authorized_for?(role)
+        caller = Runtime::Caller.current
+        return false unless caller&.actor_id
+        return false unless @dispatcher.registry.authorization_provider_for(@domain)
+
+        Ports::Authorization.holds_role?(@dispatcher.registry, actor_id: caller.actor_id, role: role,
+                                                                 as_of: caller.as_of, scope: caller.scope)
+      end
+
       def reader?(name)
         !@ir.attribute(name).nil? || @ir.lifecycle&.field&.to_sym == name
       end

data/lib/hecks/facade/surface/aggregate_door.rb

@@ -1,6 +1,7 @@
 require_relative "../../bluebook/dsl/hecksagon_builder"
 require_relative "../../bluebook/dsl/domain_port_builder"
 require_relative "../../bluebook/dsl/const_shim"
+require_relative "../../bluebook/dsl/binding_proxy"
 require_relative "../../bluebook/hexagon"
 require_relative "../handle"
 require_relative "../../naming"
@@ -164,6 +165,13 @@ module Hecks
           end
 
           door.define_singleton_method(:method_missing) do |verb, *args, **kwargs, &block|
+            # A BARE CALL starts a Privacy marking chain — see
+            # `Bluebook::DSL::BindingProxy#method_missing`'s own header;
+            # this is the same mechanism, reached when the constant is
+            # already a real, installed door (a second boot in-process)
+            # rather than a `.hecksagon`-parse-time `BindingProxy`.
+            return Bluebook::DSL::AttributePath.new(fqn, [verb.to_s]) if args.empty? && kwargs.empty? && !block
+
             collector = Bluebook::DSL::HecksagonBuilder.collector
             return super(verb, *args, **kwargs, &block) unless collector
 

data/lib/hecks/forms/field_shape.rb

@@ -4,6 +4,9 @@ require_relative "../naming"
 require_relative "value_object_shape"
 
 module Hecks
+  # The forms surface's own namespace — the `expose` DSL, the IR->HTML
+  # renderers, and the Rack app bridging them; see `forms.rb`'s own header,
+  # its primary opening, for the fuller design this implements.
   module Forms
     # One resolved field, ready for a renderer to turn into markup. A leaf
     # scalar carries `kind`/`options`/etc; a `:group` or `:list` carries

data/lib/hecks/forms/page.rb

@@ -9,6 +9,15 @@ module Hecks
     # `prefers-color-scheme` alone; nothing here reads a cookie or a query
     # param for it, so it is never wrong for the browser rendering it.
     module Page
+      # Wraps one page's own body HTML in the shared shell: doctype, head, nav, footer,
+      # inline styles and script.
+      #
+      # @param title [String] the page title, escaped into `<title>` and the browser tab
+      # @param body [String] the page's own body markup, inserted unescaped inside `<main>`
+      # @param breadcrumbs [Array<Array(String, String), Array(String, nil)>] each
+      #   `[label, href]` pair, in order; the last pair's `href` should be `nil` for the
+      #   current page
+      # @return [String] the complete HTML document
       def self.render(title:, body:, breadcrumbs: [])
         <<~HTML
           <!doctype html>
@@ -36,6 +45,11 @@ module Hecks
         HTML
       end
 
+      # Renders the breadcrumb trail as a `<nav>`, each crumb a link except the last.
+      #
+      # @param crumbs [Array<Array(String, String), Array(String, nil)>] each
+      #   `[label, href]` pair; a `nil` href renders as the current, unlinked page
+      # @return [String] the `<nav>` markup, HTML-escaped; `""` when `crumbs` is empty
       def self.breadcrumbs_html(crumbs)
         return "" if crumbs.empty?
 

data/lib/hecks/forms/port_argument.rb

@@ -22,6 +22,13 @@ module Hecks
     module PortArgument
       module_function
 
+      # Reads the `-p`/`--port` argument out of an argv array.
+      #
+      # @param argv [Array<String>] the command-line arguments, ARGV-shaped
+      # @param default [Integer] the port to use when neither spelling appears at all
+      # @return [Array(Integer, nil), Array(nil, String)] `[port, nil]` on a clean
+      #   parse, or `[nil, message]` when an explicit port was given but isn't a
+      #   real port number
       def parse(argv, default: 4567)
         equals = argv.find { |arg| arg.start_with?("--port=") }
         return resolve(equals.split("=", 2).last) if equals
@@ -32,6 +39,11 @@ module Hecks
         resolve(argv[index + 1])
       end
 
+      # Validates and converts a raw `-p`/`--port` argument value.
+      #
+      # @param value [String, nil] the text following `-p`/`--port`, or nil if none
+      # @return [Array(Integer, nil), Array(nil, String)] `[port, nil]` if `value`
+      #   is a whole number between 1 and 65535, or `[nil, message]` otherwise
       def resolve(value)
         return [nil, "-p/--port requires a value"] if value.nil? || value.empty?
         return [nil, "-p/--port must be a whole number, got #{value.inspect}"] unless value.match?(/\A\d+\z/)

data/lib/hecks/forms/query_form_renderer.rb

@@ -20,6 +20,21 @@ module Hecks
     # exactly the same kind of link on submit; and the results table once
     # a request actually supplies parameters.
     module QueryFormRenderer
+      # Renders one query's whole GET view: header, canonical link, quick links, filter
+      # form, any error, results, and the inspect panel.
+      #
+      # @param registry [Runtime::Registry] the booted registry, for resolving reference
+      #   fields' target aggregates
+      # @param domain [String] the owning chapter's name
+      # @param aggregate [Bluebook::Aggregate] the aggregate the query belongs to
+      # @param query [Bluebook::Query] the query being rendered
+      # @param action [String] the form's `action` URL and the canonical link's base
+      # @param params [Hash] the request's own query params, pre-filling the filter form
+      # @param results [Array<Hash>, nil] the query's own answer rows; `nil` renders no
+      #   results section
+      # @param error [StandardError, nil] a raised error to show in the error banner;
+      #   `nil` renders none
+      # @return [String] the page body markup
       def self.render(registry:, domain:, aggregate:, query:, action:, params: {}, results: nil, error: nil)
         fields = query.attributes.map { |a| FieldShape.resolve(a, aggregate: aggregate) }
         reference_options = ReferenceOptions.collect(registry, domain, fields)
@@ -35,6 +50,12 @@ module Hecks
         HTML
       end
 
+      # Renders the query's title, description and badges.
+      #
+      # @param domain [String] the owning chapter's name
+      # @param aggregate [Bluebook::Aggregate] the aggregate the query belongs to
+      # @param query [Bluebook::Query] the query being rendered
+      # @return [String] the header markup
       def self.header(domain, aggregate, query)
         <<~HTML
           <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}")}</h1>
@@ -43,12 +64,22 @@ module Hecks
         HTML
       end
 
+      # Renders the query's declared badges — today, just its `limit` when it declares one.
+      #
+      # @param query [Bluebook::Query] the query being rendered
+      # @return [String] the badge markup; `""` when the query declares no `limit`
       def self.badges(query)
         parts = []
         parts << %(<span class="badge">limit #{Escape.html(query.limit.to_h[:value])}</span>) if query.limit
         parts.join
       end
 
+      # Renders the query's plain-GET canonical link template, one `path={path}` per
+      # parameter.
+      #
+      # @param action [String] the query's base URL
+      # @param fields [Array<Forms::Field>] the resolved field tree naming the parameters
+      # @return [String] the help text and the templated link markup
       def self.canonical_link(action, fields)
         paths = Params.paths(fields)
         template = paths.empty? ? action : "#{action}?#{paths.map { |path| "#{path}={#{path}}" }.join('&')}"
@@ -64,6 +95,12 @@ module Hecks
       # 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.
+      #
+      # @param action [String] the query's base URL
+      # @param fields [Array<Forms::Field>] the resolved field tree to search for a
+      #   `:select` or `:radio` field
+      # @return [String] one clickable link per option of the first closed-set field
+      #   found; `""` when no field is `:select` or `:radio`
       def self.quick_links(action, fields)
         field = fields.find { |f| %i[select radio].include?(f.kind) }
         return "" unless field
@@ -75,6 +112,14 @@ module Hecks
         %(<div class="example-links">#{links.join}</div>)
       end
 
+      # Renders the GET filter form covering every declared parameter.
+      #
+      # @param action [String] the form's `action` URL
+      # @param fields [Array<Forms::Field>] the resolved field tree to render
+      # @param params [Hash] the request's own query params, pre-filling each field
+      # @param reference_options [Hash{String => Array<Array(String, String)>, nil}] each
+      #   `:reference` field's own dropdown options, as `ReferenceOptions.collect` returns
+      # @return [String] the form markup; `""` when the query declares no parameters
       def self.filter_form(action, fields, params, reference_options)
         return "" if fields.empty?
 
@@ -86,6 +131,10 @@ module Hecks
         HTML
       end
 
+      # Renders a raised error as a dismissable-looking alert banner.
+      #
+      # @param error [StandardError, nil] the error to show
+      # @return [String] the banner markup; `""` when `error` is `nil`
       def self.error_banner(error)
         return "" unless error
 
@@ -93,12 +142,26 @@ module Hecks
           "#{Escape.html(error.message)}</p></div>"
       end
 
+      # Renders the results heading and table, once a request actually supplied
+      # parameters.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose fields shape the table
+      # @param results [Array<Hash>, nil] the query's own answer rows
+      # @param domain [String] the owning chapter's name, for building record links
+      # @return [String] the results section markup; `""` when `results` is `nil`
       def self.results_section(aggregate, results, domain)
         return "" unless results
 
         "<h2>Results (#{results.size})</h2>#{RecordTable.render(aggregate, results, domain: domain)}"
       end
 
+      # Renders a collapsed panel with the query's own parameter list and raw IR JSON.
+      #
+      # @param domain [String] the owning chapter's name
+      # @param aggregate [Bluebook::Aggregate] the aggregate the query belongs to
+      # @param query [Bluebook::Query] the query being rendered
+      # @param fields [Array<Forms::Field>] the resolved field tree, for the parameter list
+      # @return [String] the `<details>` panel markup
       def self.inspect_panel(domain, aggregate, query, fields)
         verb = "#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}"
         paths = Params.paths(fields)

data/lib/hecks/forms/record_renderer.rb

@@ -11,6 +11,12 @@ module Hecks
     # do (facade/surface/aggregate_door.rb) — so they exist for every
     # aggregate whether or not its bluebook declared a query at all.
     module RecordRenderer
+      # Renders the index page listing every record of one aggregate.
+      #
+      # @param registry [Runtime::Registry] the booted registry holding the domain
+      # @param domain [String, Symbol] the domain name
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose records are listed
+      # @return [String] the index page's rendered HTML
       def self.index(registry:, domain:, aggregate:)
         instances = registry.repository(domain, aggregate).all
         <<~HTML
@@ -23,6 +29,12 @@ module Hecks
         HTML
       end
 
+      # Renders the "+ Command" buttons for every creating command.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose creating commands
+      #   are linked
+      # @return [String] HTML action buttons, or `""` if the aggregate declares none
       def self.creating_links(domain, aggregate)
         creators = aggregate.commands.select(&:creates?)
         return "" if creators.empty?
@@ -34,6 +46,15 @@ module Hecks
         %(<div class="actions">#{links.join}</div>)
       end
 
+      # Renders one record's state page: its current fields, plus the commands and
+      # queries it can dispatch next.
+      #
+      # @param registry [Runtime::Registry] the booted registry holding the domain
+      # @param domain [String, Symbol] the domain name
+      # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
+      # @param id [String, Object] the record's identity
+      # @return [String, nil] the record page's rendered HTML, or nil if no record
+      #   has that id
       def self.show(registry:, domain:, aggregate:, id:)
         instance = registry.repository(domain, aggregate).find(id)
         return nil unless instance
@@ -50,6 +71,10 @@ module Hecks
         HTML
       end
 
+      # Renders a record's state as an HTML field table.
+      #
+      # @param state [Hash{Symbol => Object}] the record's stored attribute values
+      # @return [String] an HTML table of the state's fields, values escaped
       def self.state_table(state)
         rows = state.map do |key, value|
           "<tr><th>#{Escape.html(Humanize.label(key.to_s))}</th><td>#{Escape.html(render_value(value))}</td></tr>"
@@ -60,6 +85,10 @@ module Hecks
       # `Value.materialize` first — a stored field is a `Runtime::Value`
       # wherever its attribute is a value object, not a plain Hash (see
       # record_table.rb's own note on the same read).
+      #
+      # @param value [Object] a stored field's value, possibly a `Runtime::Value`
+      # @return [String] the value rendered as text: a Hash as `"key: value, ..."`
+      #   pairs, an Array `;`-joined, anything else its own `to_s`
       def self.render_value(value)
         case (value = Runtime::Value.materialize(value))
         when Hash then value.map { |k, v| "#{k}: #{render_value(v)}" }.join(", ")
@@ -72,6 +101,14 @@ module Hecks
       # 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.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
+      # @param id [String, Object] the record's identity
+      # @param current_state [String, nil] the record's current lifecycle state, or
+      #   nil if the aggregate has no lifecycle field or it is unset
+      # @return [String] an HTML list of admissible command links, or a message
+      #   when no command currently applies
       def self.command_links(domain, aggregate, id, current_state)
         commands = aggregate.commands.reject(&:creates?).select { |cmd| applies?(aggregate, cmd, current_state) }
         return "<p><em>No commands act on an existing #{Escape.html(aggregate.hecks_name)}.</em></p>" if commands.empty?
@@ -88,6 +125,14 @@ module Hecks
         %(<ul class="verb-list">#{items.join}</ul>)
       end
 
+      # Whether the aggregate's lifecycle admits dispatching `command` from
+      # `current_state`.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate the command belongs to
+      # @param command [Bluebook::Command] the command to check
+      # @param current_state [String, nil] the record's current lifecycle state
+      # @return [Boolean] true if the aggregate declares no lifecycle transitions for
+      #   this command, or one of them admits `current_state`
       def self.applies?(aggregate, command, current_state)
         transitions = aggregate.lifecycle&.transitions_for(command.hecks_name) || []
         return true if transitions.empty?
@@ -95,6 +140,12 @@ module Hecks
         transitions.any? { |t| t.from.nil? || Array(t.from).map(&:to_s).include?(current_state.to_s) }
       end
 
+      # Renders the "Queries" link list for an aggregate's own queries.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose queries are linked
+      # @return [String] an HTML section listing every query, or `""` if the
+      #   aggregate declares none
       def self.query_links(domain, aggregate)
         return "" if aggregate.queries.empty?
 
@@ -105,6 +156,13 @@ module Hecks
         %(<h2>Queries</h2><ul class="verb-list">#{items.join}</ul>)
       end
 
+      # Renders the full command-and-query index for an aggregate, independent of
+      # any one record's state.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose verbs are listed
+      # @return [String] an HTML section listing every non-creating command and every
+      #   query, or `""` if the aggregate declares neither
       def self.verb_list(domain, aggregate)
         commands = aggregate.commands.reject(&:creates?)
         return "" if commands.empty? && aggregate.queries.empty?

data/lib/hecks/forms/record_table.rb

@@ -19,12 +19,26 @@ module Hecks
     # query's own results (query_form_renderer.rb) — the same records
     # read the same columns either way.
     module RecordTable
+      # Picks which fields to show as columns: identity, lifecycle state, then scalar
+      # attributes, capped at seven.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose records will be shown
+      # @return [Array<Symbol>] up to 7 unique field names, in that order; excludes
+      #   reference and list attributes
       def self.columns(aggregate)
         lifecycle = aggregate.lifecycle&.field
         scalars = aggregate.attributes.reject { |a| a.reference? || a.list? }.map(&:name)
         [*aggregate.identity_heads, lifecycle, *scalars].compact.uniq.first(7)
       end
 
+      # Renders a list of records as an HTML table, one row per record.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate the records belong to
+      # @param instances [Array<Runtime::Instance, Forms::Record>] the records to render;
+      #   anything answering `#id`/`#state` works
+      # @param domain [String] the owning chapter's name, for building each row's link
+      # @return [String] the table markup; `"<p><em>No records.</em></p>"` when
+      #   `instances` is empty
       def self.render(aggregate, instances, domain:)
         cols = columns(aggregate)
         head = (["id"] + cols).map { |name| "<th>#{Escape.html(Humanize.label(name.to_s))}</th>" }.join
@@ -39,6 +53,13 @@ module Hecks
         HTML
       end
 
+      # Renders one record's own table row, linked to its show page.
+      #
+      # @param instance [Runtime::Instance, Forms::Record] the record to render
+      # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
+      # @param cols [Array<Symbol>] the column field names, as `columns` returns them
+      # @param domain [String] the owning chapter's name, for building the row's link
+      # @return [String] the `<tr>` markup
       def self.row(instance, aggregate, cols, domain)
         cells = cols.map { |name| "<td>#{Escape.html(cell(instance, name))}</td>" }.join
         # L12 — the id is free-form (S3): percent-encoded as the path
@@ -50,6 +71,12 @@ module Hecks
         "<tr><td><a href=\"#{Escape.attr(href)}\">#{Escape.html(instance.id)}</a></td>#{cells}</tr>"
       end
 
+      # Reads one field's value for display, unwrapped to a single cell value.
+      #
+      # @param instance [Runtime::Instance, Forms::Record] the record to read
+      # @param name [Symbol] the field name to read
+      # @return [Object] the field's own value; for a Hash-shaped value object, its
+      #   first member's value; `""` for `nil`
       def self.cell(instance, name)
         # `state` holds `Runtime::Value` wherever an attribute is a value
         # object, not a plain Hash — `.materialize` is the runtime's own

data/lib/hecks/forms/reference_options.rb

@@ -7,12 +7,27 @@ module Hecks
     # resolve against the same repository the same way, and neither word
     # owns this more than the other.
     module ReferenceOptions
+      # Collects every `:reference` field's own dropdown options out of a resolved field
+      # tree.
+      #
+      # @param registry [Runtime::Registry] the booted registry to read repositories from
+      # @param domain [String] the owning chapter's name
+      # @param fields [Array<Forms::Field>] the resolved field tree to search
+      # @return [Hash{String => Array<Array(String, String)>, nil}] one entry per
+      #   `:reference` field found, keyed by its `path`; `nil` when the field's target
+      #   could not be resolved or its options could not be read
       def self.collect(registry, domain, fields)
         targets = {}
         walk(fields) { |field| targets[field.path] = field.target_aggregate if field.kind == :reference }
         targets.transform_values { |aggregate| aggregate && options_for(registry, domain, aggregate) }
       end
 
+      # Visits every field in a tree, depth-first, including each `:list`/`:group`
+      # field's own children.
+      #
+      # @param fields [Array<Forms::Field>] the field tree to walk
+      # @yieldparam field [Forms::Field] each field visited, parent before children
+      # @return [void]
       def self.walk(fields, &block)
         fields.each do |field|
           block.call(field)
@@ -20,6 +35,15 @@ module Hecks
         end
       end
 
+      # Reads up to 200 records' ids as `<select>` options, for one reference field's
+      # target aggregate.
+      #
+      # @param registry [Runtime::Registry] the booted registry to read the repository from
+      # @param domain [String] the owning chapter's name
+      # @param aggregate [Bluebook::Aggregate] the referenced aggregate to list
+      # @return [Array<Array(String, String)>, nil] up to 200 `[id, id]` pairs; `nil` when
+      #   the repository cannot be resolved (a wiring gap degrades to a plain text id
+      #   input, not a 500)
       def self.options_for(registry, domain, aggregate)
         registry.repository(domain, aggregate).all.first(200).map { |instance| [instance.id, instance.id] }
       rescue StandardError

data/lib/hecks/forms/value_object_shape.rb

@@ -18,6 +18,8 @@ module Hecks
       # every money-shaped VO in the corpus spells it exactly this way,
       # the two-attribute convention the language itself never enforces
       # but every real chapter follows.
+      # @param value_object [Bluebook::ValueObject] the value object to classify
+      # @return [Boolean] true if its attributes are exactly `cents` and `currency`
       def money?(value_object)
         value_object.attributes.map { |a| a.name.to_s }.sort == %w[cents currency]
       end
@@ -27,6 +29,10 @@ module Hecks
       # [[feedback_name_the_scalar_field]]'s own reasoning, shared here
       # rather than re-decided per caller. Returns the sole attribute,
       # or nil for anything else.
+      #
+      # @param value_object [Bluebook::ValueObject] the value object to inspect
+      # @return [Bluebook::Attribute, nil] its one declared attribute, or nil if
+      #   it declares zero or more than one
       def sole_attribute(value_object)
         return nil unless value_object.attributes.size == 1
 
@@ -38,6 +44,10 @@ module Hecks
       # money-shaped (money's own two members are handled by `money?`
       # instead, since which one governs ordering is a money-specific
       # decision, not a general "pick the first number" one).
+      #
+      # @param value_object [Bluebook::ValueObject] the value object to inspect
+      # @return [Bluebook::Attribute, nil] its first Integer- or Float-typed
+      #   attribute, or nil if it declares none
       def numeric_member(value_object)
         value_object.attributes.find { |a| %w[Integer Float].include?(a.type.to_s) }
       end

data/lib/hecks/fqn.rb

@@ -8,10 +8,35 @@ module Hecks
 
     attr_reader :realm, :domain, :version, :aggregate, :verb, :kind
 
+    # Builds the FQN of one command on an aggregate.
+    #
+    # @param realm [String, nil] deployment identity from the world, or nil for an
+    #   unrealmed address
+    # @param domain [String] the domain name
+    # @param aggregate [String] the aggregate name the command belongs to
+    # @param command [String] the command's PascalCase verb
+    # @param version [String, nil] the pinned domain version, or nil for the
+    #   world's configured latest alias
+    # @return [Fqn] the command address
+    # @raise [Fqn::Invalid] if any segment is empty or contains a separator, or if
+    #   `command` is not a valid PascalCase command name
     def self.command(realm:, domain:, aggregate:, command:, version: nil)
       new(realm: realm, domain: domain, version: version, aggregate: aggregate, verb: command, kind: :command)
     end
 
+    # Builds the FQN of one query, either on an aggregate or domain-level.
+    #
+    # @param realm [String, nil] deployment identity from the world, or nil for an
+    #   unrealmed address
+    # @param domain [String] the domain name
+    # @param query [String] the query's snake_case verb
+    # @param aggregate [String, nil] the aggregate the query belongs to, or nil for
+    #   a domain-level read model
+    # @param version [String, nil] the pinned domain version, or nil for the
+    #   world's configured latest alias
+    # @return [Fqn] the query address
+    # @raise [Fqn::Invalid] if any segment is empty or contains a separator, or if
+    #   `query` is not a valid snake_case query name
     def self.query(realm:, domain:, query:, aggregate: nil, version: nil)
       new(realm: realm, domain: domain, version: version, aggregate: aggregate, verb: query, kind: :query)
     end
@@ -22,6 +47,13 @@ module Hecks
     # kind) the step before it derived; splitting would mean threading all of
     # them back out as parameters/returns between new methods, for no
     # readability gain over reading the pipeline top to bottom once.
+    #
+    # @param text [String] a `Realm::Domain::Aggregate.verb` address, with domain
+    #   optionally `@version`-pinned and aggregate optional for a domain-level query
+    # @return [Fqn] the parsed address
+    # @raise [Fqn::Invalid] if `text` is not shaped like a FQN, its verb is neither
+    #   PascalCase nor snake_case, its domain version is malformed, or it names a
+    #   domain-level command
     # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def self.parse(text)
       head, separator, verb = text.to_s.rpartition(".")
@@ -53,9 +85,28 @@ module Hecks
       new(realm: realm, domain: domain, version: version, aggregate: aggregate, verb: verb, kind: kind)
     end
 
+    # Whether `name` is a valid command verb: PascalCase.
+    #
+    # @param name [String, Symbol, #to_s] the candidate verb
+    # @return [Boolean] true if `name` matches the PascalCase command shape
     def self.command_name?(name) = /\A[A-Z][A-Za-z0-9]*\z/.match?(name.to_s)
+
+    # Whether `name` is a valid query verb: snake_case.
+    #
+    # @param name [String, Symbol, #to_s] the candidate verb
+    # @return [Boolean] true if `name` matches the snake_case query shape
     def self.query_name?(name)   = /\A[a-z][a-z0-9_]*\z/.match?(name.to_s)
 
+    # @param realm [String, nil] deployment identity from the world, or nil for an
+    #   unrealmed address
+    # @param domain [String] the domain name
+    # @param aggregate [String, nil] the aggregate name, or nil for a domain-level query
+    # @param verb [String] the command or query verb
+    # @param kind [Symbol, String] `:command` or `:query`
+    # @param version [String, nil] the pinned domain version, or nil for the
+    #   world's configured latest alias
+    # @raise [Fqn::Invalid] if any segment is empty or contains a separator, or if
+    #   `verb` does not match the shape required by `kind`
     def initialize(realm:, domain:, aggregate:, verb:, kind:, version: nil)
       @realm     = realm && segment(realm, "realm")
       @domain    = segment(domain, "domain")
@@ -68,7 +119,14 @@ module Hecks
       raise Invalid, "#{@kind} FQN has an invalid verb #{@verb.inspect}" unless valid
     end
 
+    # Whether this address names a command.
+    #
+    # @return [Boolean] true if this address's kind is `:command`
     def command? = @kind == :command
+
+    # Whether this address names a query.
+    #
+    # @return [Boolean] true if this address's kind is `:query`
     def query?   = @kind == :query
 
     def to_s