hecks 1.3.0 → 1.4.0

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

@@ -9,17 +9,27 @@ module Hecks
       # singleton, one aggregate door per declared head, and the
       # declaration hook for names the door does not carry.
       module Chapter
+        # Builds the anonymous module that stands for one booted chapter: `vision`,
+        # `aggregates`, `docs`, `narrate` and `project` as singleton methods, plus one
+        # nested constant per aggregate holding that aggregate's door.
+        #
+        # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
+        #   dispatcher each aggregate door closes over
+        # @param bluebook [Bluebook::Chapter] the chapter to project into a module
+        # @return [Module] a fresh, unnamed module; `Surface.install` gives it its
+        #   top-level name
+        # @raise [NameError] if an aggregate's name is not a valid constant name
         def chapter_module(dispatcher, bluebook)
           chapter = Module.new
           chapter.define_singleton_method(:vision)     { bluebook.vision }
           chapter.define_singleton_method(:aggregates) { bluebook.aggregates.map(&:name).sort }
 
-          # THE CHAPTER, EXPLAINING ITSELF. `Projector::DocsProjector` reads
+          # **The chapter, explaining itself**. `Projector::DocsProjector` reads
           # nothing but this bluebook's own IR, so the document cannot drift
           # from the domain — the same guarantee `bin/reference` gives the DSL
           # reference by generating it from the Syntax chapter.
           #
-          # A METHOD RATHER THAN ONLY A SCRIPT because that is what gets it
+          # A method rather than only a script because that is what gets it
           # read: `QualityControl.docs` in a console, beside `vision` and
           # `aggregates`, at the moment somebody is wondering what a verb
           # wants. Projected on each call rather than memoised — it is a pure
@@ -29,14 +39,14 @@ module Hecks
             Projector.call(:docs, bluebook: bluebook, options: options)
           end
 
-          # THE CHAPTER, READ BACK IN ENGLISH — `Projector::NarrateProjector`
+          # **The chapter, read back in english** — `Projector::NarrateProjector`
           # beside `:docs`, for the reader who needs to confirm the domain is
           # right rather than call it: `QualityControl.narrate` in a console.
           chapter.define_singleton_method(:narrate) do |**options|
             Projector.call(:narrate, bluebook: bluebook, options: options)
           end
 
-          # THE DOMAIN'S OWN IR, PROJECTED. `Projector` has taken
+          # **The domain's own IR, projected**. `Projector` has taken
           # `call(name, bluebook:, options:)` since §30, but nothing could
           # reach it from a booted domain — this module already closes
           # over the one `Bluebook` every projector wants and simply
@@ -69,26 +79,25 @@ module Hecks
             chapter.const_set(aggregate.hecks_name, aggregate_module(dispatcher, bluebook.name, aggregate))
           end
 
-          # INSIDE A HECKSAGON, A NAME IS A DECLARATION, NOT A LOOKUP. A
-          # `.hecksagon` may name an aggregate this door does not carry — a STALE
-          # door from an earlier boot resolving another registry's chapter, the
-          # exact hazard the constant tree used to hide by reinstalling on every
-          # load. With a collector open, the name becomes a `BindingProxy`
+          # Inside a hecksagon, a name is a declaration, not a lookup. A
+          # `.hecksagon` may name an aggregate this door does not carry — a stale
+          # door from an earlier boot resolving another registry's chapter, which
+          # can happen because the facade is installed once a boot finishes, not
+          # on every load. With a collector open, the name becomes a `BindingProxy`
           # recording the same bind the aggregate module would ; without one, it
-          # is a genuine NameError, exactly as before.
+          # is a genuine NameError.
           #
-          # THE OTHER READER OF A MISS is S0b's own bridge (docs/dsl-work-
+          # The other reader of a miss is S0b's own bridge (docs/dsl-work-
           # slices.md, const_shim.rb's `ScopedConstant`): a bluebook still being
-          # DECLARED that names `#{bluebook.name}::Something` — an event, a
-          # command reference, an `admits:` — reaches HERE, not
+          # declared that names `#{bluebook.name}::Something` — an event, a
+          # command reference, an `admits:` — reaches here, not
           # `Object.const_missing`, the moment this chapter's own facade already
           # exists (a previous boot in the same process, or this same chapter
           # re-entering its own name). `ConstShim.active?` is exactly as true
           # here as it is at the top level, mid-declaration, and consulting the
-          # SAME resolver is what makes a scoped reference resolve identically
-          # whether or not a facade happens to be built yet — the earlier
-          # attempt's own failure mode (this file's own history) was a bridge
-          # that worked only BEFORE any facade existed.
+          # same resolver is what makes a scoped reference resolve identically
+          # whether or not a facade happens to be built yet — a bridge consulted
+          # only at the top level works only before any facade exists.
           chapter.define_singleton_method(:const_missing) do |name|
             collector = Bluebook::DSL::HecksagonBuilder.collector
             return Bluebook::DSL::BindingProxy.new("#{bluebook.name}::#{name}", collector) if collector

data/lib/hecks/facade/surface.rb

@@ -3,9 +3,9 @@ require_relative "surface/aggregate_door"
 
 module Hecks
   module Facade
-    # THE DOOR, WITHOUT THE CLASSES.
+    # **The door, without the classes**.
     #
-    # `Pizzas::Pizza.create_pizza(...)` is the public surface (HANDOVER rule 3),
+    # `Pizzas::Pizza.create_pizza!(...)` is the public surface (handover rule 3),
     # and this is what serves it now : anonymous per-boot modules whose
     # singleton methods close over the dispatcher and dispatch by FQN — the
     # same shape `Router::NamespaceInstaller` proved. Nothing here is a domain
@@ -17,7 +17,7 @@ module Hecks
     # The hexagon-binding door rides along : `Pizzas::Pizza.persisted_by("Heki")`
     # in a `.hecksagon` file lands on the module's `method_missing`, which
     # records an `Bind` into whatever `HecksagonBuilder.collector` is open
-    # AT CALL TIME — so even a facade left over from a previous boot records
+    # at call time — so even a facade left over from a previous boot records
     # into the current builder, and a chapter with no constant at all falls
     # through to `ConstShim` → `BindingProxy`, which mints byte-identical binds.
     module Surface
@@ -30,6 +30,19 @@ module Hecks
 
       module_function
 
+      # Installs one top-level module per booted chapter, and one per aggregate, each
+      # closing over `dispatcher`, so `Pizzas::Pizza` and the bare `Pizza` both open the
+      # door of the boot that ran last.
+      #
+      # An aggregate sharing its chapter's name gets no second constant: the chapter
+      # module already holds that name. A name that user code or the stdlib already owns
+      # is left alone with a warning (see `Namespace.install`).
+      #
+      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
+      #   dispatcher every installed door dispatches and queries through
+      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the same `dispatcher`,
+      #   so a boot can return the call's result
+      # @raise [NameError] if a chapter or aggregate name is not a valid constant name
       def install(dispatcher)
         dispatcher.registry.bluebooks.each_value do |bluebook|
           chapter = chapter_module(dispatcher, bluebook)

data/lib/hecks/facade.rb

@@ -7,15 +7,15 @@ module Hecks
 
   # The one careful way to put something at top level.
   #
-  # Overwrites only what it itself installed (tracked in GENERATED), refuses —
+  # Overwrites only what it itself installed (tracked in `GENERATED`), refuses —
   # with a warning, never a raise — to clobber a constant belonging to user
   # code or the stdlib. Which is why a chapter named `Set` never becomes a
   # constant, and why `Registry` keeps its own table of chapters rather than
-  # trusting Ruby's. Each re-install REPLACES the previous boot's entry, so
-  # what GENERATED retains is one small facade module per name, not a graph
+  # trusting Ruby's. Each re-install replaces the previous boot's entry, so
+  # what `GENERATED` retains is one small facade module per name, not a graph
   # per boot.
   module Namespace
-    # NOT frozen — a real registry, mutated below
+    # Not frozen — a real registry, mutated below
     # (`GENERATED[[container, name]] = value`). False positive for
     # Style/MutableConstant.
     # rubocop:disable-next Style/MutableConstant
@@ -23,6 +23,17 @@ module Hecks
 
     module_function
 
+    # Sets `container::name` to `value`, replacing only a constant this module installed
+    # itself and leaving any other existing constant in place with a warning.
+    #
+    # @param container [Module] the namespace to define the constant in; every caller in
+    #   this repository passes `Object`
+    # @param name [String, Symbol] the constant name, such as a chapter or aggregate name
+    # @param value [Module] the facade module to install under that name
+    # @return [Object] `value` when it was installed; otherwise the constant already
+    #   defined under `name`, which this module does not own and did not replace
+    # @raise [NameError] if `name` is not a valid constant name (raised by
+    #   `const_defined?`)
     def install(container, name, value)
       name = name.to_s
 

data/lib/hecks/forms/app.rb

@@ -14,17 +14,24 @@ 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
+    # 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
+    # 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.
     class App
+      # Builds the Rack app for a configured app name, exposing exactly the chapters its
+      # `Forms.configure` block declared.
+      #
+      # @param registry [Runtime::Registry] the booted registry holding the exposed chapters
+      # @param app_name [String, Symbol] the name an earlier `Forms.configure` call registered
+      # @return [Forms::App] a Rack app routing only the configured chapters
+      # @raise [ArgumentError] if no app of that name has been configured
       def self.for(registry:, app_name:)
         config = Forms.config(app_name) ||
                  raise(ArgumentError, "no app #{app_name.inspect} configured — " \
@@ -32,12 +39,23 @@ module Hecks
         new(registry: registry, exposed: config.exposes)
       end
 
+      # @param registry [Runtime::Registry] the booted registry holding the exposed chapters
+      # @param exposed [Array<String>] names of the chapters (domains) this app routes; a
+      #   request for any other domain is answered 404
+      # @param dispatcher [Runtime::Dispatcher, nil] the dispatcher commands and queries go
+      #   through; nil builds a `Runtime::Dispatcher` over `registry`
       def initialize(registry:, exposed:, dispatcher: nil)
         @registry   = registry
         @exposed    = exposed
         @dispatcher = dispatcher || Runtime::Dispatcher.new(registry)
       end
 
+      # Answers one Rack request, routing on the path and its trailing `.html`/`.json` format;
+      # an unknown or unexposed route is answered as a plain-text 404 rather than raised.
+      #
+      # @param env [Hash{String => Object}] the Rack environment for the request
+      # @return [Array(Integer, Hash{String => String}, Array<String>)] the Rack response
+      #   triple of status, headers and body
       def call(env)
         request = Rack::Request.new(env)
         route(request)
@@ -81,19 +99,18 @@ 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) — splitting on the
-      # FIRST "." truncated any identity value containing a dot (an email
+      # 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` 404'd everywhere: detail page, JSON view, and
-      # its own index-table link. Only a LITERAL trailing ".html"/".json"
-      # now counts as a format — every other dot in the segment is just
-      # part of the identity. An identity that itself happens to end in
+      # `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), but that was already true before this fix and is not
-      # this bug.
+      # suffix — the same tension any extension-based content-negotiation
+      # scheme has, and not what H12 is about.
       def split_format(segment)
         segment = segment.to_s
         return [Regexp.last_match(1), Regexp.last_match(2)] if segment =~ /\A(.*)\.(html|json)\z/
@@ -123,11 +140,11 @@ 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
+          # 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 used to silently clobber the correct bare
-          # identity when merged first.
+          # already, which silently clobbers the correct bare identity
+          # if `id:` is merged first.
           json(200, instances.map { |i| i.state.merge(id: i.id) })
         end
       end
@@ -141,14 +158,13 @@ module Hecks
         # 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
+        # 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 (the previous order) meant a
-        # record unlucky enough to be named after a real verb could never
-        # be viewed again. POST never means "view a record" at all
-        # (`record_route` only ever answers GET), so command submission
-        # there is unambiguous and is left to match the verb first, same
-        # as before.
+        # 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.
         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
@@ -187,7 +203,7 @@ module Hecks
 
       def submit_command(request, domain, aggregate, command, action)
         raw, envelope = submitted_command(request, aggregate, command)
-        result = @dispatcher.dispatch("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}", **envelope)
+        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.
         redirect("/#{domain}/#{aggregate.hecks_name}/#{Escape.path(result.id)}.html")
@@ -201,8 +217,8 @@ module Hecks
         return respond(405, "text/plain", "GET or POST only") unless request.post?
 
         _, envelope = submitted_command(request, aggregate, command)
-        result = @dispatcher.dispatch("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}", **envelope)
-        # id LAST — same reasoning as the other JSON-serializing call
+        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).
         json(201, result.state.merge(id: result.id))
       rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError, JSON::ParserError => e
@@ -239,7 +255,7 @@ 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
+        # id last — same reasoning as the other JSON-serializing call
         # sites in this file (see aggregate_route's own comment).
         json(200, results.map { |i| i.state.merge(id: i.id) })
       end
@@ -259,10 +275,10 @@ module Hecks
       # 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 — both command submission paths
-      # already rescue it (`submit_command`, `command_json`); this one
-      # didn't, so a malformed list-of-VO query 500'd instead of showing
-      # the same 422 every other bad-input path shows.
+      # 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.
       rescue *Runtime::DOMAIN_REFUSALS, ArgumentError, TypeError, JSON::ParserError => e
         [nil, e]
       end
@@ -272,7 +288,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
+        # id last — same reasoning as the other JSON-serializing call
         # sites in this file (see aggregate_route's own comment).
         return json(200, instance.state.merge(id: instance.id)) if format != "html"
 

data/lib/hecks/forms/command_form_renderer.rb

@@ -13,22 +13,46 @@ module Hecks
     # renders through here — nothing here is per-command code; see that
     # doc for the 1:1 rule this deliberately holds to for now.
     module CommandFormRenderer
-      # `registry` is only used 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.
-      # The SAME field list a POST handler needs to cast raw params against
+      # 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.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate that declares the command
+      # @param command [Bluebook::Command] the command the form submits
+      # @return [Array<Forms::Field>] the form's top-level fields, in render order
+      # @raise [Bluebook::DSL::Malformed] if a `reference_to` attribute cannot say which
+      #   aggregate declares it
       def self.fields_for(aggregate, command)
         addressing = command.creates? ? [] : [identity_field(aggregate)]
         addressing + command.attributes.map { |a| FieldShape.resolve(a, aggregate: aggregate) }
       end
 
+      # 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.
+      #
+      # @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 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
+      # @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)
         reference_options = ReferenceOptions.collect(registry, domain, all_fields)
@@ -48,12 +72,24 @@ module Hecks
         HTML
       end
 
+      # Builds the `to` field a non-creating command uses to name the record it acts on,
+      # labelled with the aggregate's identity paths.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose records the picker offers
+      # @return [Forms::Field] a `:reference` field at path `"to"` targeting `aggregate`
       def self.identity_field(aggregate)
         Field.new(path: "to", label: "#{aggregate.hecks_name} (#{aggregate.identity_paths.join(', ')})",
                   kind: :reference, html_type: "text", target_aggregate: aggregate,
                   help: "The record this command acts on.")
       end
 
+      # Renders the form's heading: the command's qualified name, its role and creates
+      # badges, its goal, and its preconditions callout.
+      #
+      # @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 being described
+      # @return [String] HTML for the heading block
       def self.header(domain, aggregate, command)
         <<~HTML
           <h1>#{Escape.html("#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}")}</h1>
@@ -64,6 +100,11 @@ module Hecks
         HTML
       end
 
+      # Renders the command's `given` preconditions as a callout, so a caller sees what
+      # would refuse the submission before making it.
+      #
+      # @param command [Bluebook::Command] the command whose givens are listed
+      # @return [String] HTML for the callout, or `""` when the command declares no givens
       def self.givens_callout(command)
         return "" if command.givens.empty?
 
@@ -71,6 +112,11 @@ module Hecks
         %(<div class="callout"><strong>Preconditions</strong> — refused if any fail:<ul>#{items.join}</ul></div>)
       end
 
+      # Renders a refused submission as an alert banner carrying the refusal's class name
+      # (without its namespace) and message.
+      #
+      # @param error [Exception, nil] the refusal raised by the submission
+      # @return [String] HTML for the banner, or `""` when `error` is nil
       def self.error_banner(error)
         return "" unless error
 
@@ -81,14 +127,29 @@ module Hecks
         HTML
       end
 
+      # 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.
+      #
+      # @param _error [Exception, nil] the refusal raised by the submission; ignored
+      # @return [Hash] always empty; keys would be dotted field paths
       def self.field_errors(_error) = {}
 
+      # Renders the collapsed "Inspect" panel: the events the command emits, an equivalent
+      # `curl` request, its field paths, and its declaration as JSON.
+      #
+      # @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 being described
+      # @param action [String] URL path the form posts to, shown in the `curl` line
+      # @param fields [Array<Forms::Field>] the form's fields, as `fields_for` returns them
+      # @return [String] HTML for the `<details>` panel
       def self.inspect_panel(domain, aggregate, command, action, fields)
         verb = "#{domain}::#{aggregate.hecks_name}.#{command.hecks_name}"
         paths = Params.paths(fields)