hecks 2.8.0 → 3.0.0

data/lib/hecks/forms/app.rb

@@ -7,23 +7,13 @@ require_relative "record_renderer"
 require_relative "command_form_renderer"
 require_relative "query_form_renderer"
 require_relative "params"
-require_relative "../facade/command_request"
-require_relative "../facade/json_door"
+require_relative "../doors/command_request"
+require_relative "../doors/json_door"
 
 module Hecks
   module Forms
-    # The content-negotiated router: `GET /Banking/Account/Overdrawn.html`
-    # renders the query view built in this directory; the identical path
-    # with no extension (or `.json`) dispatches the same ask through
-    # `Runtime::Dispatcher#query` and answers with its raw result — one
-    # route, two representations, exactly the "change the file format on
-    # the route" mechanism this was built around
-    # (docs/command-form-and-query-form-bluebook.md).
-    #
-    # A plain Rack app (`#call(env)`) — no Sinatra, no Rails. `rack` itself
-    # is a lazy dependency the same way `pg`/`oauth2`/`aws-sdk-lambda` are
-    # for their own adapters (see the Gemfile's own comment) : a project
-    # that never boots this file never needs it installed.
+    # A Rack app that content-negotiates one route: `/Banking/Account/Overdrawn.html`
+    # renders HTML, and the same path with no extension or `.json` answers JSON.
     class App
       # Builds the Rack app for a configured app name, exposing exactly the chapters its
       # `Forms.configure` block declared.
@@ -99,18 +89,8 @@ module Hecks
         raise RouteNotFound, "#{domain.inspect} is not exposed by this app — declared chapters: #{@exposed.join(', ')}"
       end
 
-      # H12 (docs/audits/2026-08-10-main-bug-audit.md) — only a literal
-      # trailing ".html"/".json" counts as a format; every other dot in the
-      # segment is just part of the identity. Splitting on the first "."
-      # instead truncates any identity value containing a dot (an email
-      # `identified_by { email.address }`, a decimal-ish reference — an
-      # aggregate's identity is free-form unless its value object declares
-      # a `pattern:`, see S3 in the same audit) at its own first dot, so
-      # `reference.value=c.1` 404s everywhere: detail page, JSON view, and
-      # its own index-table link. An identity that itself happens to end in
-      # exactly ".html" or ".json" is still ambiguous with a real format
-      # suffix — the same tension any extension-based content-negotiation
-      # scheme has, and not what H12 is about.
+      # Only a trailing ".html"/".json" is a format; other dots belong to the identity
+      # (an email, say). An identity ending in ".html" or ".json" stays ambiguous.
       def split_format(segment)
         segment = segment.to_s
         return [Regexp.last_match(1), Regexp.last_match(2)] if segment =~ /\A(.*)\.(html|json)\z/
@@ -118,8 +98,6 @@ module Hecks
         [segment, "json"]
       end
 
-      # ---- home -------------------------------------------------------
-
       def home(request)
         format = request.params["format"] || "html"
         chapters = @exposed.to_h { |name| [name, @registry.bluebook(name)] }.compact
@@ -128,8 +106,6 @@ module Hecks
         html("Exposed domains", IndexRenderer.render(chapters))
       end
 
-      # ---- /:domain/:aggregate.:format ---------------------------------
-
       def aggregate_route(request, chapter, aggregate_name, format)
         aggregate = find_aggregate(chapter, aggregate_name)
         return respond(405, "text/plain", "GET only") unless request.get?
@@ -140,31 +116,17 @@ module Hecks
                breadcrumbs: [[chapter.name, "/"], [aggregate.hecks_name, nil]])
         else
           instances = @registry.repository(chapter.name, aggregate).all
-          # id last — see Instance#to_h's own comment: an aggregate free
-          # to declare its own attribute literally named `id` has that
-          # attribute's own wrapped value sitting in `i.state[:id]`
-          # already, which silently clobbers the correct bare identity
-          # if `id:` is merged first.
+          # `id:` is merged last so an attribute named `id` in the state cannot clobber it.
           json(200, instances.map { |i| i.state.merge(id: i.id) })
         end
       end
 
-      # ---- /:domain/:aggregate/:verb_or_id.:format ----------------------
-
       def verb_or_record_route(request, chapter, aggregate_name, verb_or_id, format)
         aggregate = find_aggregate(chapter, aggregate_name)
         domain = chapter.name
 
-        # L11 (docs/audits/2026-08-10-main-bug-audit.md) — a record's own
-        # id is free-form (S3) and can collide with one of its own
-        # aggregate's command/query names ("Close", "Overdrawn", ...).
-        # A GET for such an id must still be able to reach that record's
-        # own detail page when a record with that literal id actually
-        # exists — checking the verb first would mean a record unlucky
-        # enough to be named after a real verb could never be viewed.
-        # POST never means "view a record" at all (`record_route` only
-        # ever answers GET), so command submission there is unambiguous
-        # and matches the verb first.
+        # A record id is free-form and can equal a verb name ("Close"), so a GET checks for
+        # a record first. POST never views a record, so it matches the verb first.
         if request.get? && (instance = @registry.repository(domain, aggregate).find(verb_or_id))
           return record_route(request, domain, aggregate, verb_or_id, format, instance: instance)
         end
@@ -204,8 +166,7 @@ module Hecks
       def submit_command(request, domain, aggregate, command, action)
         raw, envelope = submitted_command(request, aggregate, command)
         result = @dispatcher.dispatch_flat("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}", envelope)
-        # L12 — the id is free-form (S3), so it must be percent-encoded as
-        # a path segment here, not just interpolated raw.
+        # The id is free-form, so it is percent-encoded as a path segment.
         redirect("/#{domain}/#{aggregate.hecks_name}/#{Escape.path(result.id)}.html")
       rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError, JSON::ParserError => e
         status = e.is_a?(Runtime::NotFound) ? 404 : 422
@@ -218,8 +179,7 @@ module Hecks
 
         _, envelope = submitted_command(request, aggregate, command)
         result = @dispatcher.dispatch_flat("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}", envelope)
-        # id last — same reasoning as the other JSON-serializing call
-        # sites in this file (see aggregate_route's own comment).
+        # `id:` last, as in `aggregate_route`.
         json(201, result.state.merge(id: result.id))
       rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError, JSON::ParserError => e
         status = e.is_a?(Runtime::NotFound) ? 404 : 422
@@ -255,30 +215,18 @@ module Hecks
         results, error = run_query(domain, aggregate, query, fields, asked)
         return json(422, { error: error.class.name.split("::").last, message: error.message }) if error
 
-        # id last — same reasoning as the other JSON-serializing call
-        # sites in this file (see aggregate_route's own comment).
+        # `id:` last, as in `aggregate_route`.
         json(200, results.map { |i| i.state.merge(id: i.id) })
       end
 
-      # `Dispatcher#query` answers an array of plain hashes
-      # (`{id:}.merge(state)`, flattened by `QueryInterpreter#call` on
-      # every path it can take — native pushdown or the in-memory
-      # fallback alike), not `Runtime::Instance`. Wrapped into `Record`
-      # here, once, so every renderer downstream reads one shape whether
-      # its records came from a query or straight off a repository.
+      # `Dispatcher#query` answers plain hashes, not `Runtime::Instance`; wrapping them
+      # in `Record` gives the renderers one shape.
       def run_query(domain, aggregate, query, fields, asked)
         args = Params.extract(fields, asked)
         rows = @dispatcher.query("#{domain}::#{aggregate.hecks_name}.#{query.hecks_name}", **args)
         [rows.map { |row| Record.new(row[:id], row.except(:id)) }, nil]
-      # L10 (docs/audits/2026-08-10-main-bug-audit.md) — `Params.extract`
-      # (params.rb's `extract_list`) reads a list-of-value-object line as
-      # JSON (the honest fallback for a multi-attribute list element this
-      # prototype's textarea doesn't build a second widget for). A caller
-      # who types a non-JSON line into that field raises `JSON::ParserError`
-      # before dispatch ever sees it. It is rescued here, as both command
-      # submission paths rescue it (`submit_command`, `command_json`), so
-      # a malformed list-of-VO query shows the same 422 every other
-      # bad-input path shows rather than a 500.
+      # `Params.extract` parses a list-of-value-object line as JSON; rescuing
+      # `JSON::ParserError` turns a malformed line into a 422 rather than a 500.
       rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError, JSON::ParserError => e
         [nil, e]
       end
@@ -288,8 +236,7 @@ module Hecks
 
         instance ||= @registry.repository(domain, aggregate).find(id)
         return not_found(aggregate, id, format) unless instance
-        # id last — same reasoning as the other JSON-serializing call
-        # sites in this file (see aggregate_route's own comment).
+        # `id:` last, as in `aggregate_route`.
         return json(200, instance.state.merge(id: instance.id)) if format != "html"
 
         html("#{domain}::#{aggregate.hecks_name} #{id}",
@@ -311,16 +258,16 @@ module Hecks
       end
 
       def command_envelope(command, args)
-        Facade::CommandRequest.normalize(args, receiver: command_receiver(command), legacy_receiver: :id)
+        Doors::CommandRequest.normalize(args, receiver: command_receiver(command), legacy_receiver: :id)
       end
 
       def command_receiver(command) = command.creates? ? nil : :aggregate
 
       def submitted_command(request, aggregate, command)
         if request.media_type == "application/json"
-          raw = Facade::JsonDoor.parse(request.body.read)
-          envelope = Facade::JsonDoor.command_request(raw, receiver:        command_receiver(command),
-                                                           legacy_receiver: :id)
+          raw = Doors::JsonDoor.parse(request.body.read)
+          envelope = Doors::JsonDoor.command_request(raw, receiver:        command_receiver(command),
+                                                          legacy_receiver: :id)
           return [raw, envelope]
         end
 
@@ -339,8 +286,6 @@ module Hecks
         raw.merge("to" => raw["id"])
       end
 
-      # ---- rendering ----------------------------------------------------
-
       def html(title, body, breadcrumbs: [], status: 200)
         respond(status, "text/html; charset=utf-8", Page.render(title: title, body: body, breadcrumbs: breadcrumbs))
       end

data/lib/hecks/forms/banking_presentation.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../forms"
+require_relative "port_argument"
+
+module Hecks
+  module Forms
+    # The banking example, wired for the forms app: its bluebook, an in-memory store for every
+    # aggregate, and the `expose` sample that renders it.
+    #
+    # It is what `hecks present` serves. The `expose` sample stays out of `examples/`, since every
+    # entry there is scanned as a corpus member and must be a complete, model-checked domain.
+    module BankingPresentation
+      # The aggregates of the banking example, each held in memory.
+      AGGREGATES = %w[Customer Account SafeDepositBox Transfer ATMCard CardPayment ExternalTransfer
+                      ScheduledPayment OnboardingCase Statement].freeze
+
+      module_function
+
+      # Builds the Rack app for the banking example.
+      #
+      # @param root [String] the checkout's root
+      # @return [#call] the app, for a Rack server
+      def app(root:)
+        registry = Hecks::Runtime::Registry.new
+        Hecks.with_registry(registry) { load_into(registry, root) }
+        registry.verify!
+        Hecks::Forms::App.for(registry: registry, app_name: "BankingConsole")
+      end
+
+      # @api private
+      def load_into(_registry, root)
+        %w[lib/hecks/ports/persistence.port lib/hecks/ports/extraction.port
+           lib/hecks/adapters/driven/memory.adapter lib/hecks/adapters/driven/prism.adapter].each do |file|
+          Kernel.load(File.join(root, file))
+        end
+        Hecks::Adapters::Folder.new.load_bluebooks(File.join(root, "examples/banking/bluebook"))
+        Kernel.load(File.join(root, "lib/hecks/forms/examples/banking_console.bluebook"))
+        Hecks.hecksagon("Banking") do
+          uses_framework "Governance"
+          AGGREGATES.each { |name| ::Banking.const_get(name).persisted_by("Memory") }
+        end
+        Hecks.hecksagon("Governance") do
+          ::Governance::RoleAssignment.persisted_by("Memory")
+          ::Governance::RoleTransition.persisted_by("Memory")
+        end
+      end
+    end
+  end
+end

data/lib/hecks/forms/command_form_renderer.rb

@@ -7,18 +7,14 @@ require_relative "params"
 
 module Hecks
   module Forms
-    # Command -> the page body for its HTML form — the working half of
-    # what `command_form.bluebook` names (see docs/command-form-and-query-
-    # form-bluebook.md). Every command in every loaded, exposed bluebook
-    # renders through here — nothing here is per-command code; see that
-    # doc for the 1:1 rule this deliberately holds to for now.
+    # Renders a command as the page body of its HTML form; no per-command code
+    # (see docs/command-form-and-query-form-bluebook.md).
     module CommandFormRenderer
       # Lists every field a command's form shows: the `to` identity picker first (unless the
       # command creates its aggregate), then one field per command attribute.
       #
-      # The same field list a POST handler needs to cast raw params against
-      # (params.rb's `Params.extract`) — one derivation, so a page never
-      # renders an input the submit handler doesn't also expect.
+      # The same list `Params.extract` casts a POST against, so a page never renders
+      # an input the submit handler does not expect.
       #
       # @param aggregate [Bluebook::Aggregate] the aggregate that declares the command
       # @param command [Bluebook::Command] the command the form submits
@@ -33,25 +29,14 @@ module Hecks
       # Renders the page body for one command: header, refusal banner, the form itself, and
       # the inspect panel.
       #
-      # `registry` serves only to populate a `:reference` field's
-      # `<select>` with real records (including the identity picker itself,
-      # for a non-creating command — see `identity_field` below). `values`/
-      # `error` carry a sticky re-render after a refused submission; leave
-      # both nil for a fresh form. `prefill` carries values a caller
-      # arrived with (typically `?to=...` off a record's own detail page) —
-      # kept separate from `values` because a prefill is not an error retry
-      # and should not be treated as one by a future reader of this code.
+      # `registry` populates `:reference` selects. `values` and `error` re-render after a
+      # refusal; `prefill` carries values the caller arrived with (`?to=...`), not a retry.
       #
       # @param registry [Runtime::Registry] the booted registry, read for reference options
-      # @param domain [String] name of the domain (chapter) the aggregate belongs to
-      # @param aggregate [Bluebook::Aggregate] the aggregate that declares the command
-      # @param command [Bluebook::Command] the command the form submits
       # @param action [String] URL path the form posts to
-      # @param values [Hash{String => Object}, nil] the raw submission to re-show after a
-      #   refusal, keyed by dotted field path; nil falls back to `prefill`
+      # @param values [Hash{String => Object}, nil] raw submission to re-show; nil uses `prefill`
       # @param error [Exception, nil] the refusal to show in the banner; nil for a fresh form
-      # @param prefill [Hash{String => String}] values the caller arrived with, keyed by
-      #   dotted field path; ignored when `values` is given
+      # @param prefill [Hash{String => String}] values the caller arrived with, by dotted path
       # @return [String] the HTML page body, without the surrounding page chrome
       def self.render(registry:, domain:, aggregate:, command:, action:, values: nil, error: nil, prefill: {})
         all_fields = fields_for(aggregate, command)
@@ -130,12 +115,8 @@ module Hecks
       # Maps a refusal to per-field messages; always empty, so every refusal is shown in
       # the banner rather than beside a field.
       #
-      # No structured field attribution exists on a domain refusal today
-      # (it is a typed exception with a rendered message — see
-      # docs/command-form-and-query-form-bluebook.md's note on
-      # `RefusalWording`), so this returns empty rather than guessing which
-      # field a message meant; the banner above carries the real text
-      # instead of a misattributed hint.
+      # A domain refusal carries no field attribution, so the banner shows the message
+      # instead of guessing a field.
       #
       # @param _error [Exception, nil] the refusal raised by the submission; ignored
       # @return [Hash] always empty; keys would be dotted field paths

data/lib/hecks/forms/field_renderer.rb

@@ -4,31 +4,13 @@ require_relative "../naming"
 
 module Hecks
   module Forms
-    # A Field (field_shape.rb) -> the `<div class="field">...</div>` or
-    # `<fieldset>...</fieldset>` markup for it. One renderer, called
-    # recursively for a group's children, shared by CommandFormRenderer
-    # (POST) and QueryFormRenderer (GET) — the same attribute shape asks
-    # for the same input either way; only the surrounding `<form>`'s
-    # method differs.
+    # Renders a Field (field_shape.rb) as form markup, recursing into a group's children.
+    # Shared by CommandFormRenderer (POST) and QueryFormRenderer (GET).
     module FieldRenderer
-      # Renders one field, and recursively a group's children, as form markup with any held
-      # value filled back in.
+      # Renders one field, filling any held value back in.
       #
-      # `values` is the hash a sticky re-render (a rejected command,
-      # a submitted query) carries back — read with the same dotted path a
-      # Field already carries, via `dig`. `reference_options` maps a
-      # `:reference` field's own path to `[[id, label], ...]`, built by the
-      # caller (it needs a repository; this module stays pure markup).
-      #
-      # @param field [Forms::Field] the field to render
-      # @param values [Hash{String, Symbol => Object}] held values, either flat and keyed by
-      #   dotted path or nested by path segment; see `dig`
-      # @param errors [Hash{String => String}, nil] message per dotted field path; nil for none
-      # @param reference_options [Hash{String => Array<Array>, nil}] `[id, label]` pairs per
-      #   `:reference` field path, as `ReferenceOptions.collect` builds them; a nil or empty
-      #   entry renders a plain text input
-      # @return [String] HTML for the field: a `<fieldset>` for `:group` and `:money`, a
-      #   `<div class="field">` otherwise
+      # `reference_options` is built by the caller, since it needs a repository and
+      # this module stays pure markup.
       def self.render(field, values: {}, errors: nil, reference_options: {})
         case field.kind
         when :group  then group(field, values, errors, reference_options, tag: "fieldset")
@@ -38,17 +20,6 @@ module Hecks
         end
       end
 
-      # Renders a field's children inside one enclosing element, with the field's label as
-      # its `<legend>`.
-      #
-      # @param field [Forms::Field] a `:group` or `:money` field carrying `children`
-      # @param values [Hash{String, Symbol => Object}] held values; see `dig`
-      # @param errors [Hash{String => String}, nil] message per dotted field path
-      # @param reference_options [Hash{String => Array<Array>, nil}] `[id, label]` pairs per
-      #   `:reference` field path
-      # @param tag [String] name of the enclosing element, such as `"fieldset"`
-      # @param css [String, nil] class attribute for the enclosing element; nil for none
-      # @return [String] HTML for the enclosing element and every child
       def self.group(field, values, errors, reference_options, tag:, css: nil)
         inner = field.children.map { |child| render(child, values: values, errors: errors, reference_options: reference_options) }
         <<~HTML
@@ -59,14 +30,7 @@ module Hecks
         HTML
       end
 
-      # Renders a `:list` field as one textarea taking an element per line, which is the shape
-      # `Params.extract_list` reads back.
-      #
-      # @param field [Forms::Field] a `:list` field whose first child describes one element
-      # @param values [Hash{String, Symbol => Object}] held values; the list's entry may be an
-      #   Array, a newline-joined String, or absent
-      # @param _errors [Hash{String => String}, nil] ignored; a list shows no per-field message
-      # @return [String] HTML for the labelled textarea and its help line
+      # One textarea, an element per line: the shape `Params.extract_list` reads back.
       def self.list(field, values, _errors)
         item = field.children.first
         current = Array(dig(values, field.path)).join("\n")
@@ -80,15 +44,6 @@ module Hecks
         HTML
       end
 
-      # Renders a single-value field with the control its `kind` calls for, wrapped with its
-      # label, help text and error.
-      #
-      # @param field [Forms::Field] a leaf field
-      # @param values [Hash{String, Symbol => Object}] held values; see `dig`
-      # @param errors [Hash{String => String}, nil] message per dotted field path
-      # @param reference_options [Hash{String => Array<Array>, nil}] `[id, label]` pairs per
-      #   `:reference` field path
-      # @return [String] HTML for the `<div class="field">` block
       def self.leaf(field, values, errors, reference_options)
         value = dig(values, field.path)
         error = errors && errors[field.path]
@@ -103,14 +58,7 @@ module Hecks
         wrap(field, body, error)
       end
 
-      # Wraps a rendered control with its label, help text and error message; a `:boolean`
-      # gets no label here because `checkbox` renders its own beside the box.
-      #
-      # @param field [Forms::Field] the field the control belongs to
-      # @param body [String] HTML of the control itself
-      # @param error [String, nil] message shown as an alert; nil for none
-      # @return [String] HTML for the `<div class="field">` block, classed `has-error` when
-      #   `error` is given
+      # A :boolean gets no label here because `checkbox` renders its own beside the box.
       def self.wrap(field, body, error)
         <<~HTML
           <div class="field#{' has-error' if error}">
@@ -122,13 +70,6 @@ module Hecks
         HTML
       end
 
-      # Renders an `<input>` of the field's `html_type`, falling back to the field's default
-      # for a missing value; a whole-cents number also gets a live preview span.
-      #
-      # @param field [Forms::Field] a leaf field
-      # @param value [Object, nil] the held value, rendered with `to_s`; nil shows the default
-      # @return [String] HTML for the input, followed by the preview `<span>` when the field
-      #   is a `:number` whose help text mentions cents
       def self.input(field, value)
         money = field.kind == :number && field.help.to_s.include?("cents")
         tag = Tag.void("input", id: dom_id(field.path), name: field.path, type: field.html_type,
@@ -140,23 +81,11 @@ module Hecks
         %(#{tag} <span id="#{dom_id(field.path)}-preview" class="mono help" aria-live="polite"></span>)
       end
 
-      # Renders a `<textarea>` holding the value as escaped text; unlike `input`, the field's
-      # default is not filled in.
-      #
-      # @param field [Forms::Field] a `:textarea` field
-      # @param value [Object, nil] the held value, rendered with `to_s`; nil renders empty
-      # @return [String] HTML for the textarea
       def self.textarea(field, value)
         %(<textarea id="#{dom_id(field.path)}" name="#{Escape.attr(field.path)}" #{aria(field)}>#{Escape.html(value)}</textarea>)
       end
 
-      # Renders a checkbox preceded by a hidden `"0"` input of the same name, so an unticked
-      # box still submits a value, with the field's label beside it.
-      #
-      # @param field [Forms::Field] a `:boolean` field
-      # @param value [Boolean, String, nil] the held value; `true`, `"true"`, `"on"` and `"1"`
-      #   tick the box, and nil falls back to a default of exactly `true`
-      # @return [String] HTML for the checkbox row
+      # The hidden "0" input makes an unticked box still submit a value.
       def self.checkbox(field, value)
         checked = value.nil? ? field.default == true : [true, "true", "on", "1"].include?(value)
         <<~HTML
@@ -168,13 +97,6 @@ module Hecks
         HTML
       end
 
-      # Renders one radio button per option, pre-checking the one equal to the held value or,
-      # failing that, to the field's default.
-      #
-      # @param field [Forms::Field] a `:radio` field whose `options` are `[value, label]` pairs
-      # @param value [Object, nil] the held value, compared with `to_s`; nil falls back to the
-      #   default
-      # @return [String] HTML for the `<div role="radiogroup">` block
       def self.radio_group(field, value)
         selected = value || field.default
         options = field.options.map do |option_value, option_label|
@@ -187,13 +109,6 @@ module Hecks
         %(<div class="radio-group" role="radiogroup">#{options.join}</div>)
       end
 
-      # Renders a `<select>` over the field's fixed options, with a blank "—" entry first when
-      # the field is optional.
-      #
-      # @param field [Forms::Field] a `:select` field whose `options` are `[value, label]` pairs
-      # @param value [Object, nil] the held value, compared with `to_s`; nil falls back to the
-      #   default
-      # @return [String] HTML for the select
       def self.select(field, value)
         selected = value || field.default
         options = field.options.map do |option_value, option_label|
@@ -204,16 +119,7 @@ module Hecks
         %(<select id="#{dom_id(field.path)}" name="#{Escape.attr(field.path)}" #{aria(field)}>#{blank}#{options.join}</select>)
       end
 
-      # Renders a `<select>` of existing records for a `:reference` field, degrading to a plain
-      # text id input when no records are on offer.
-      #
-      # @param field [Forms::Field] a `:reference` field; its `html_type` is set to `"text"`
-      #   in place when the text fallback is taken
-      # @param value [Object, nil] the held id, compared with `to_s`; nil preselects the
-      #   disabled "choose one…" entry of a required field
-      # @param options [Array<Array>, nil] `[id, label]` pairs to offer; nil or empty takes the
-      #   text fallback
-      # @return [String] HTML for the select, or for the fallback `<input>`
+      # Falls back to a plain text id input when no records are on offer.
       def self.reference_select(field, value, options)
         return input(field.tap { |f| f.html_type = "text" }, value) unless options && !options.empty?
 
@@ -228,78 +134,33 @@ module Hecks
         %(<select id="#{dom_id(field.path)}" name="#{Escape.attr(field.path)}" #{aria(field)}>#{blank}#{rendered.join}</select>)
       end
 
-      # Renders the asterisk that marks a required field's label or legend.
-      #
-      # @param field [Forms::Field] the field being labelled
-      # @return [String] HTML for the mark, or `""` when the field is optional
       def self.required_mark(field) = field.required? ? %(<span class="required-mark" title="required">*</span>) : ""
 
-      # Derives the element id of a field's control from its dotted path, such as
-      # `"f-amount-cents"` for `"amount.cents"`.
-      #
-      # @param path [String, Symbol] the field's dotted path
-      # @return [String] the id, `"f-"` followed by the path with dots turned to hyphens
+      # "amount.cents" -> "f-amount-cents".
       def self.dom_id(path) = "f-#{path.to_s.tr('.', '-')}"
 
-      # Picks the `pattern` attribute an input carries, withholding it from a `:reference`
-      # field, whose input takes a record id rather than the attribute's own value.
-      #
-      # @param field [Forms::Field] a leaf field
-      # @return [String, nil] the regex source the attribute declares as `pattern:`; nil for a
-      #   `:reference` field or when none is declared
+      # A :reference input takes a record id, so the attribute's own pattern must not apply.
       def self.leaf_pattern(field) = field.kind == :reference ? nil : field.pattern
 
-      # Names the preview span a whole-cents input's `data-money-cents` attribute points at.
-      #
-      # @param field [Forms::Field] the cents field
-      # @return [String] a CSS id selector, such as `"#f-amount-cents-preview"`
       def self.money_preview_target(field) = "##{dom_id(field.path)}-preview"
 
-      # Renders the `required` and `aria-describedby` attributes of a control as an
-      # attribute string, for the controls assembled by hand rather than through `Tag.void`.
-      #
-      # @param field [Forms::Field] the field the control belongs to
-      # @return [String] the rendered attributes, or `""` when the field is optional and has
-      #   no help text
+      # String form, for controls assembled by hand rather than through `Tag.void`.
       def self.aria(field)
         Tag.attrs(required: field.required?, aria_describedby: field.help ? "#{dom_id(field.path)}-help" : nil)
       end
 
-      # Builds the `required` and `aria-describedby` attributes of a control as a Hash, to
-      # splat into `Tag.void`.
-      #
-      # @param field [Forms::Field] the field the control belongs to
-      # @return [Hash{Symbol => Boolean, String, nil}] `:required` and `:aria_describedby`;
-      #   the latter is the help span's element id, or nil when the field has no help text
+      # Hash form of `aria`, to splat into `Tag.void`.
       def self.aria_attrs(field)
         { required: field.required?, aria_describedby: field.help ? "#{dom_id(field.path)}-help" : nil }
       end
 
-      # Reads the value held for a dotted field path out of either spelling a form's values
-      # arrive in, flat or nested, without losing a stored `false`.
-      #
-      # `values` is a nested hash; `path` a dotted string using the same
-      # segment spelling the hash keys are built from (`Params.nest` in
-      # params.rb) — symbols one level down from a group, strings at the
-      # flat top when a sticky POST re-render hands raw params back untouched.
-      #
-      # @param values [Hash{String, Symbol => Object}, Object] held values; anything that is
-      #   not a Hash, nil included, reads as nil
-      # @param path [String, Symbol] the field's dotted path, such as `"amount.cents"`
-      # @return [Object, nil] the held value exactly as stored (a raw form String, or a typed
-      #   value from a record's state); nil when no key on the path answers
+      # Reads the value held for a dotted path from either a flat or a nested values hash.
       def self.dig(values, path)
         return nil unless values.is_a?(Hash)
 
-        # A sticky re-render after a refused submission hands back the raw
-        # flat params (`{"amount.cents"=>"1050"}` — the same shape the form
-        # posted, string values and all, dotted key intact) ; a prefill from
-        # an existing record's own state hands back a nested hash instead
-        # (`{amount: {cents: 1050}}`). Flat wins when both would answer,
-        # since only the raw form is ever what the caller actually typed.
-        # `key?` decides which spelling answers, at every step below —
-        # never `||`, which would treat a genuinely-held `false` the
-        # same as an absent key and fall through to `nil`.
+        # A sticky re-render hands back raw flat params ({"amount.cents"=>"1050"}); a prefill
+        # from a record's state is nested ({amount: {cents: 1050}}). Flat wins when both answer.
+        # Test with `key?`, never `||`, so a held `false` is not mistaken for an absent key.
         str = path.to_s
         return values[str] if values.key?(str)