hecks 2.8.0 → 2.9.0

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

@@ -9,36 +9,14 @@ require_relative "../../naming"
 module Hecks
   module Facade
     module Surface
-      # One aggregate's door: creating verbs as module methods returning
-      # the record in hand, CRUD delegation to the repository, the
-      # `persisted_by`-style binding collector a `.hecksagon` lands on, and
-      # the aggregate-scoped `port` a `.hecksagon` lands on beside it.
+      # One aggregate's door: creating verbs and queries as module methods, CRUD
+      # delegation, and the `.hecksagon` binding/port hooks it lands on.
       module AggregateDoor
-        # Builds the anonymous module that is one aggregate's door: a `name!` method per
-        # creating command, a bare method per query, `find`/`all`/`count`/`events`,
-        # `project`/`docs`/`narrate`, and the `.hecksagon` binding hooks.
+        # Builds one aggregate's door module: creating-command methods, query methods,
+        # find/all/count/events, project/docs/narrate, and the port/binding hooks.
         #
-        # Warns once for each attribute whose name is in `RESERVED`.
-        #
-        # One method building one `door` module's ~20 singleton methods
-        # looks like it splits along each `define_singleton_method` call,
-        # but three of those blocks (`:port`, `:method_missing`,
-        # `:const_missing`) are a single cross-referencing essay on the
-        # stale-facade-across-boots hazard — each one's comment explicitly
-        # points at "below"/"above" as part of the same method. Splitting
-        # into helper methods wouldn't break anything at runtime (no
-        # shared mutable state beyond the closed-over args, which just
-        # become parameters), but it would sever that narrative across
-        # method boundaries for no functional gain.
-        #
-        # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
-        #   dispatcher the door's methods dispatch, query and read repositories through
-        # @param domain [String] the owning chapter's name, the first half of the
-        #   aggregate's FQN (`"Pizzas"` in `"Pizzas::Pizza"`)
-        # @param aggregate [Bluebook::Aggregate] the aggregate to build a door for
-        # @return [Module] a fresh, unnamed module carrying the door's singleton methods
-        # @raise [Bluebook::DSL::Malformed] never while building; the returned door's
-        #   `port` raises it when called with no boot in progress
+        # Kept as one method: `:port`/`:method_missing`/`:const_missing` below
+        # cross-reference each other and would lose that thread if split up.
         # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
         def aggregate_module(dispatcher, domain, aggregate)
           fqn  = "#{domain}::#{aggregate.hecks_name}"
@@ -50,16 +28,9 @@ module Hecks
             warn "[hecks] #{aggregate.hecks_name}##{attribute.name} shadows a built-in — no reader defined"
           end
 
-          # A creating verb is a module method returning the new record in hand ;
-          # a verb that reaches an existing record lives on the Handle. `!` —
-          # a command does something (mutates, may refuse), Ruby's own
-          # convention for that ; `Naming.snake` alone would leave a
-          # creating command's bare name claiming the exact spelling a
-          # query of the same business name also wants (`Account`'s own
-          # "Open" — the creating command and a query listing open
-          # accounts, a real same-aggregate collision this corpus already
-          # has) — the suffix is what makes both nameable at all, not
-          # merely a style choice.
+          # `!` marks a creating command (Ruby's mutate-and-may-refuse convention).
+          # Without it, a query sharing the same business name (e.g. Account's
+          # "Open") would collide with the creating command's own bare name.
           aggregate.commands.select(&:creates?).each do |command|
             door.define_singleton_method("#{Naming.snake(command.hecks_name)}!") do |**args|
               Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate,
@@ -67,12 +38,8 @@ module Hecks
             end
           end
 
-          # A query is a module method too — same level as a creating
-          # command, since neither needs an existing record in hand — but
-          # bare: a query reads and returns, nothing to warn a caller
-          # about the way `!` does for a command. Answers the raw row
-          # array `dispatcher.query` itself answers, the same shape
-          # `runtime.query("#{fqn}.Name")` already gave.
+          # A query is a bare module method (no `!`): it just reads and returns
+          # the same raw row array `dispatcher.query` itself answers.
           aggregate.queries.each do |query|
             door.define_singleton_method(Naming.snake(query.hecks_name)) do |**args|
               dispatcher.query("#{fqn}.#{query.hecks_name}", **args)
@@ -82,16 +49,9 @@ module Hecks
           door.define_singleton_method(:fqn)        { fqn }
           door.define_singleton_method(:ir)         { aggregate }
 
-          # The same verb the chapter answers, one level down. Every
-          # construct emits its own IR (Hecks::IR), so an aggregate
-          # is a legitimate thing to project — `Pizzas::Order.project(
-          # Projections::IR)` is this aggregate's IR, not the chapter's.
-          #
-          # A chapter-scoped target refuses here rather than inventing an
-          # answer: `Projector.admits!` is what tells `Projections::IR`
-          # (`from: :any`) apart from `Projections::Shape`
-          # (`from: :chapter`), which would otherwise answer a confidently
-          # empty `{"aggregates" => []}` for an aggregate.
+          # Every construct emits its own IR, so an aggregate is a legitimate
+          # `project` target too. A chapter-scoped target refuses here via
+          # `Projector.admits!` rather than answering a confidently empty result.
           door.define_singleton_method(:project) do |target, out: nil, **options|
             key      = Projector.key_for(target)
             artifact = Projector.call(key, bluebook: aggregate, options: options)
@@ -104,16 +64,12 @@ module Hecks
             aggregate.commands.map { |c| "#{Naming.snake(c.hecks_name)}!" }.sort
           end
           door.define_singleton_method(:queries) { aggregate.queries.map { |q| Naming.snake(q.hecks_name) }.sort }
-          # **One aggregate's usage document** — the same projection the chapter
-          # answers with, narrowed to this head. `commands` above already
-          # answers "what can I call"; this answers "and what does each one
-          # want, refuse, and guarantee", which is the rest of the question.
+          # This chapter's own `:docs` projection, narrowed to this aggregate.
           door.define_singleton_method(:docs) do |**options|
             Projector.call(:docs, bluebook: dispatcher.registry.bluebook(domain),
                                   options:  options.merge(aggregate: aggregate.hecks_name))
           end
-          # **One aggregate, read back in english** — the same narrowing `:docs`
-          # takes, aimed at `:narrate` instead.
+          # Same narrowing as `:docs`, aimed at `:narrate`.
           door.define_singleton_method(:narrate) do |**options|
             Projector.call(:narrate, bluebook: dispatcher.registry.bluebook(domain),
                                      options:  options.merge(aggregate: aggregate.hecks_name))
@@ -132,44 +88,38 @@ module Hecks
             end
           end
 
-          # The same reason `method_missing` below exists at all — a facade
-          # left over from a previous boot in this process shadows the fresh
-          # `BindingProxy` a `.hecksagon` would otherwise reach through
-          # `ConstShim`/`const_missing`, so `Pizzas::Pizza.port(...)` lands
-          # here instead once any boot has run before.
-          #
-          # Re-resolved, not the closed-over `aggregate` — this door can be a
-          # stale one, built by a boot from earlier in this same process,
-          # sitting on the `Pizzas`/`Pizza` constants only because nothing
-          # has re-installed them since. Attaching to this door's own
-          # `aggregate` would attach the port to a discarded aggregate from
-          # that old boot, invisible to the current one actually being
-          # loaded — silently, the exact way `method_missing` below already
-          # has to avoid it for a plain bind, via `HecksagonBuilder.collector`
-          # rather than anything this door closes over. `Hecks.current_registry`
-          # is the same "whichever boot is actually in progress" indirection,
-          # and `BindingProxy#port` already re-resolves through it the same
-          # way — this is that door's fallback twin, not a shortcut past it.
+          # Re-resolves via `Hecks.current_registry` rather than the closed-over
+          # `aggregate`: this door can be stale from an earlier boot, and its own
+          # `aggregate` would silently port a discarded one instead of the live one.
           door.define_singleton_method(:port) do |name, &block|
             current = Hecks.current_registry&.bluebook(domain)&.aggregate(aggregate.hecks_name) or
               raise Bluebook::DSL::Malformed, "#{fqn}.port(#{name.inspect}) called outside a boot"
 
-            domain_port = Bluebook::DSL::ConstShim.with(->(const) { const }) do
+            built = Bluebook::DSL::ConstShim.with(->(const) { const }) do
               Bluebook::DSL::DomainPortBuilder.build(name, owner: current.hecks_name, &block)
             end
-            domain_port.operations.each do |operation|
+
+            # A `verb`-shaped port is a plain `Port`, the same struct `Hecks.port` registers —
+            # it belongs to no aggregate IR the way an operations-shaped `DomainPort` does, so
+            # it takes the registry's `add_port` directly. Mirrors `DSL::BindingProxy#port`,
+            # which handles the identical shape on a domain's first in-process boot (before
+            # this facade constant exists); this method is what a repeat boot reaches instead.
+            if built.is_a?(Bluebook::Port)
+              Hecks.current_registry.add_port(built)
+              return self
+            end
+
+            built.operations.each do |operation|
               operation.attributes.select(&:reference?).each { |attribute| attribute.type.declared_in = current }
             end
-            current.add_port(domain_port)
+            current.add_port(built)
             self
           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`.
+            # A bare call starts a Privacy marking chain (see
+            # `BindingProxy#method_missing`), reached here when the door is already
+            # installed (a second in-process boot) rather than at parse time.
             return Bluebook::DSL::AttributePath.new(fqn, [verb.to_s]) if args.empty? && kwargs.empty? && !block
 
             collector = Bluebook::DSL::HecksagonBuilder.collector
@@ -189,24 +139,9 @@ module Hecks
             !Bluebook::DSL::HecksagonBuilder.collector.nil? || super(name, include_private)
           end
 
-          # The same stale-facade hazard `method_missing`/`port` above already
-          # document, one door lower — `Surface.install` installs an aggregate's
-          # own name as a bare top-level constant too (`Namespace.install(Object,
-          # aggregate.hecks_name, ...)`, surface.rb's own `install`), not only
-          # nested under its chapter. So once any domain has booted once in this
-          # process, `Account::Debit` written while declaring some other
-          # bluebook — same domain or a different one — reaches this door's
-          # const_missing directly, never `Object.const_missing`/`ConstShim::
-          # Hook` at all: real modules resolve without ever calling that.
-          #
-          # `aggregate.hecks_name`, not the qualified `fqn` — a scoped
-          # reference has to read the same either way, whether or not a stale
-          # door happens to be sitting on this process from an earlier boot;
-          # qualifying it here would make `Account::Debit`'s own meaning
-          # depend on incidental process history, which is the exact
-          # instability S0b exists to remove (docs/dsl-work-slices.md — "two
-          # domains in one registry" is this file's own reason for being
-          # owned by that slice).
+          # Uses `aggregate.hecks_name`, not the qualified `fqn`: qualifying it here
+          # would make `Account::Debit`'s meaning depend on whether a stale door
+          # from an earlier boot happens to be sitting on this process.
           door.define_singleton_method(:const_missing) do |name|
             resolver = Bluebook::DSL::ConstShim.resolver
             return resolver.call("#{aggregate.hecks_name}::#{name}") if resolver

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

@@ -5,9 +5,8 @@ require_relative "../../bluebook/dsl/hecksagon_builder"
 module Hecks
   module Facade
     module Surface
-      # One chapter's module: vision and aggregate roll-call on the
-      # singleton, one aggregate door per declared head, and the
-      # declaration hook for names the door does not carry.
+      # One chapter's module: vision and aggregate list on the singleton, one
+      # aggregate door per declared head, and a `const_missing` hook for undeclared names.
       module Chapter
         # Builds the anonymous module that stands for one booted chapter: `vision`,
         # `aggregates`, `docs`, `narrate` and `project` as singleton methods, plus one
@@ -24,49 +23,22 @@ module Hecks
           chapter.define_singleton_method(:vision)     { bluebook.vision }
           chapter.define_singleton_method(:aggregates) { bluebook.aggregates.map(&:name).sort }
 
-          # **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
-          # 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
-          # read of the IR, and a stale document is the entire thing this
-          # exists to prevent.
+          # The chapter's usage document, projected from its IR on each call so it
+          # cannot go stale.
           chapter.define_singleton_method(:docs) do |**options|
             Projector.call(:docs, bluebook: bluebook, options: options)
           end
 
-          # **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.
+          # The chapter read back in english, via `Projector::NarrateProjector`.
           chapter.define_singleton_method(:narrate) do |**options|
             Projector.call(:narrate, bluebook: bluebook, options: options)
           end
 
-          # **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
-          # never handed it out, so every bin/ projector rebuilt a
-          # Registry and reloaded the files to recover what was already
-          # sitting here.
+          # Projects the chapter's IR through a target; `out:` writes the artifact and
+          # the remaining options go to the projector (`audience:` for OIDC).
           #
           #   Pizzas.project(Projections::OIDC)
           #   Pizzas.project(Projections::Shape, out: "shape.json")
-          #
-          # No `to_ir` companion: `project(Projections::IR)` already
-          # answers with the canonical serialized form, and handing out
-          # the live graph as well would be a second way to say the same
-          # thing. Anything genuinely needing the graph is a projector,
-          # and a projector is given it.
-          #
-          # `out:` writes and everything else is passed through to the
-          # target — so `options` stays the projector's own vocabulary
-          # (`audience:` for OIDC) rather than a fixed set this method
-          # would have to know about.
           chapter.define_singleton_method(:project) do |target, out: nil, **options|
             key      = Projector.key_for(target)
             artifact = Projector.call(key, bluebook: bluebook, options: options)
@@ -79,25 +51,9 @@ 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, 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.
-          #
-          # 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
-          # `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 — a bridge consulted
-          # only at the top level works only before any facade exists.
+          # Inside a hecksagon a name is a declaration: with a collector open it becomes
+          # a `BindingProxy`. Otherwise a scoped reference from a bluebook mid-declaration
+          # goes to the `ConstShim` resolver, so it resolves whether or not a 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,26 +3,13 @@ require_relative "surface/aggregate_door"
 
 module Hecks
   module Facade
-    # **The door, without the classes**.
+    # The door without classes: anonymous per-boot modules whose singleton methods
+    # dispatch by FQN, installed by `Loader.bind_runtime` and replaced whole on the next boot.
     #
-    # `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
-    # class ; the IR is the only graph, and the door is a projection of it,
-    # installed by `Loader.bind_runtime` and re-installed whole on the next
-    # boot. How a chapter's module is built is surface/chapter.rb; how one
-    # aggregate's door is built is surface/aggregate_door.rb.
-    #
-    # 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
-    # into the current builder, and a chapter with no constant at all falls
-    # through to `ConstShim` → `BindingProxy`, which mints byte-identical binds.
+    # `persisted_by("Heki")` in a `.hecksagon` file lands on the module's `method_missing`,
+    # which records a `Bind` into the open `HecksagonBuilder.collector`.
     module Surface
-      # These would shadow the machinery a Handle runs on, so a field named one
-      # of them gets no reader and says so — the same warning the class door gave.
+      # Names that would shadow the machinery a Handle runs on; a field with one gets no reader.
       RESERVED = %i[id state events reload inspect to_h hash class].freeze
 
       extend Chapter
@@ -34,14 +21,12 @@ module Hecks
       # 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`).
+      # An aggregate sharing its chapter's name gets no second constant. 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
+      # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the same `dispatcher`
       # @raise [NameError] if a chapter or aggregate name is not a valid constant name
       def install(dispatcher)
         dispatcher.registry.bluebooks.each_value do |bluebook|

data/lib/hecks/facade.rb

@@ -1,39 +1,24 @@
 module Hecks
-  # The class-free public surface — see facade/surface.rb for the door and
-  # facade/handle.rb for the record in hand. Installed per boot by
-  # `Runtime::Loader.bind_runtime`.
+  # The class-free public surface, installed per boot by `Runtime::Loader.bind_runtime`.
   module Facade
   end
 
-  # The one careful way to put something at top level.
-  #
-  # 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
-  # per boot.
+  # Installs facade constants at top level, replacing only what it installed itself.
+  # A constant owned by user code or the stdlib is left alone with a warning.
   module Namespace
-    # Not frozen — a real registry, mutated below
-    # (`GENERATED[[container, name]] = value`). False positive for
-    # Style/MutableConstant.
+    # A live registry, mutated by `install`, so it cannot be frozen.
     # rubocop:disable-next Style/MutableConstant
     GENERATED = {}
 
     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.
+    # Sets `container::name` to `value`, replacing only a constant this module installed.
     #
-    # @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?`)
+    # @param container [Module] the namespace to define the constant in
+    # @param name [String, Symbol] the constant name
+    # @param value [Module] the facade module to install
+    # @return [Object] `value` when installed, else the foreign constant left in place
+    # @raise [NameError] if `name` is not a valid constant name
     def install(container, name, value)
       name = name.to_s
 

data/lib/hecks/forms/app.rb

@@ -12,18 +12,8 @@ require_relative "../facade/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}",
@@ -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