hecks 1.0.2 → 1.2.0

data/lib/hecks/projections/glossary.rb

@@ -0,0 +1,374 @@
+require_relative "../projector"
+
+module Hecks
+  module Projections
+    # A CHAPTER, PROJECTED AS ITS UBIQUITOUS LANGUAGE — one glossary
+    # entry per term the business actually uses: the Domain itself, and
+    # every Aggregate, Entity, Value Object, Command (a verb), Query (a
+    # question), Read Model, Event, Role, Lifecycle, Saga, and Policy it
+    # declares — every BUSINESS-domain construct the language's own §30
+    # reference distinguishes. Deliberately not the deployment/wiring
+    # half (World, Hecksagon, Port, Adapter, Translation): Evans'
+    # Ubiquitous Language is the business model, not the plumbing that
+    # runs it.
+    #
+    # GROUPED UNDER THE AGGREGATE EACH TERM BELONGS TO — a reader thinks
+    # "what does Account mean" before they think "what starts with A",
+    # so a term's home is the aggregate that declares it (an Entity's
+    # own Commands/Queries/Lifecycle nest under ITS aggregate, not
+    # listed as their own peer); an Event or a Policy that reacts to one
+    # nests under the aggregate whose command actually raises it — the
+    # same "who does this" a reader would ask by hand. Only what
+    # genuinely belongs to no single aggregate (a Role, issued across
+    # several; a Read Model, joined across several) gets its own
+    # trailing section. Within a section, still one short sentence per
+    # term, dictionary-plain — this is not `DocsProjector` re-sorted
+    # (verbs, refusals, wire shapes, walked for a caller); it is what
+    # each term MEANS, walked for a domain expert.
+    #
+    # WHAT IT DELIBERATELY DOES NOT DO: invent, same discipline as
+    # `DocsProjector`. A term with no declared prose (most value objects;
+    # every event and role, which the language only ever spells as bare
+    # strings — a command's `emits:`/`role:`) gets a definition DERIVED
+    # from the graph around it — what it's shaped like, what emits it,
+    # who issues it — never a restated name standing in for a sentence
+    # nobody wrote.
+    #
+    #   Projector.call(:glossary, bluebook: <the Bluebook chapter>)
+    module Glossary
+      extend Projector::Target
+
+      projects_as :glossary
+
+      Entry = Struct.new(:term, :kind, :definition, :within, :section, keyword_init: true)
+
+      # DISPLAY ORDER WITHIN A SECTION — the aggregate's own row first
+      # (what it IS), then the shapes it can be in and hold, then what
+      # you can ask of it, then what happens on its own.
+      KIND_RANK = {
+        "Aggregate" => 0, "Lifecycle" => 1, "Entity" => 2, "Value Object" => 3,
+        "Command" => 4, "Query" => 5, "Event" => 6, "Policy" => 7, "Saga" => 8
+      }.freeze
+
+      ROLES_SECTION       = "Roles".freeze
+      READ_MODELS_SECTION = "Read Models".freeze
+
+      module_function
+
+      def call(bluebook:, options: {}) = render(bluebook)
+
+      # ── gathering ─────────────────────────────────────────────────────
+
+      # AN ENTITY CAN CARRY ITS OWN COMMANDS, QUERIES, AND VALUE OBJECTS
+      # TOO — walked the same one level down `DocsProjector` and
+      # `Projections::Diagrams` already walk it, so a domain's entity
+      # gaining any of these needs no change here either.
+      def holders(bluebook)
+        bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
+      end
+
+      # EVERY HOLDER'S OWN AGGREGATE, ONE HOP OR ZERO — an aggregate
+      # maps to itself, an entity to whichever aggregate declared it.
+      # This is the single fact the whole grouping is built on: a
+      # Command/Query/Lifecycle's `within` already names its holder, so
+      # looking that name up here is enough to find its SECTION even
+      # when the holder is an entity two levels down from the chapter.
+      def holder_aggregate(bluebook)
+        bluebook.aggregates.each_with_object({}) do |aggregate, map|
+          map[aggregate.hecks_name] = aggregate.hecks_name
+          aggregate.entities.each { |entity| map[entity.hecks_name] = aggregate.hecks_name }
+        end
+      end
+
+      # EVERY EVENT'S OWN AGGREGATE — an event is never declared, only
+      # emitted, so its home is whichever aggregate the FIRST command
+      # that raises it belongs to. A policy or saga reacting to that
+      # event inherits the same home, the same way a reader tracing the
+      # reaction by hand would: "what raises this, and whose is that."
+      def event_aggregate(bluebook, holder_aggregate)
+        map = {}
+        holders(bluebook).each do |holder|
+          home = holder_aggregate[holder.hecks_name]
+          holder.commands.each { |command| command.emits.each { |event| map[event] ||= home } }
+        end
+        map
+      end
+
+      def entries(bluebook)
+        holder_agg = holder_aggregate(bluebook)
+        event_agg  = event_aggregate(bluebook, holder_agg)
+
+        entries = []
+        entries += domain_entries(bluebook)
+        entries += aggregate_entries(bluebook)
+        entries += entity_entries(bluebook, holder_agg)
+        entries += value_object_entries(bluebook, holder_agg)
+        entries += command_entries(bluebook, holder_agg)
+        entries += query_entries(bluebook, holder_agg)
+        entries += read_model_entries(bluebook)
+        entries += event_entries(bluebook, event_agg)
+        entries += role_entries(bluebook)
+        entries += lifecycle_entries(bluebook, holder_agg)
+        entries += saga_entries(bluebook, event_agg)
+        entries += policy_entries(bluebook, event_agg)
+        entries
+      end
+
+      # THE CHAPTER ITSELF, AS A TERM — the one construct every other
+      # entry here lives inside (`Hecks.bluebook "Banking" do ... end`),
+      # and the one place `vision` — the single sentence written for a
+      # reader who doesn't know the domain yet — actually lives. Given
+      # no `section` (rendered once, at the very top, above every
+      # aggregate) since it is the one term that belongs to no aggregate
+      # by being the thing that holds them all.
+      def domain_entries(bluebook)
+        [Entry.new(term: bluebook.name, kind: "Domain", definition: bluebook.vision)]
+      end
+
+      def aggregate_entries(bluebook)
+        bluebook.aggregates.map do |aggregate|
+          Entry.new(term: aggregate.hecks_name, kind: "Aggregate", definition: aggregate.description,
+                    section: aggregate.hecks_name)
+        end
+      end
+
+      def entity_entries(bluebook, holder_agg)
+        bluebook.aggregates.flat_map do |aggregate|
+          aggregate.entities.map do |entity|
+            Entry.new(term: entity.hecks_name, kind: "Entity", within: aggregate.hecks_name,
+                      section: holder_agg[aggregate.hecks_name], definition: entity.description)
+          end
+        end
+      end
+
+      # A VALUE OBJECT CARRIES NO `description` — the language never gave
+      # it one (`Bluebook::ValueObject` declares `attributes`,
+      # `invariants`, `members`, `closed_set`, nothing else). Its
+      # definition is derived from its own shape instead: a closed set
+      # states its members, an open one its fields — the same
+      # distinction `DocsProjector#shape_of` draws.
+      #
+      # AGGREGATES ONLY, not `holders` — unlike commands and queries, an
+      # entity declares no value objects of its own (`Bluebook::Entity`
+      # deliberately does not answer `value_objects`; its argument types
+      # live on the aggregate above it, same as `DocsProjector#value_object_for`
+      # already has to account for).
+      def value_object_entries(bluebook, holder_agg)
+        bluebook.aggregates.flat_map do |aggregate|
+          aggregate.value_objects.map do |vo|
+            Entry.new(term: vo.hecks_name, kind: "Value Object", within: aggregate.hecks_name,
+                      section: holder_agg[aggregate.hecks_name], definition: value_object_definition(vo))
+          end
+        end
+      end
+
+      # THE SHAPE, THEN THE RULES — a value object's own `invariant`
+      # bodies are real authored prose ("a currency is a three-letter
+      # code"), not derived the way the shape above is, and were
+      # sitting unread by this projector until now: `to_h`'s own
+      # `invariants` field already carries them, one `description` per
+      # `Bluebook::Invariant`.
+      def value_object_definition(value_object)
+        sentence = value_object_shape(value_object)
+        rules = value_object.invariants.map(&:description)
+        sentence += " Must satisfy: #{rules.join('; ')}." unless rules.empty?
+        sentence
+      end
+
+      # A CLOSED SET'S ROWS, not just their first field — the same
+      # correction `Projections::Vocabulary` already had to make
+      # (`StatementFrequency` names retention months and a paper fee
+      # alongside its cadence; flattening every field into one list
+      # produces well-formed nonsense, same as it did there).
+      def value_object_shape(value_object)
+        if value_object.closed_set?
+          if value_object.members.first && value_object.members.first.size > 1
+            rows = value_object.members.map { |row| "{ #{row.map { |f, v| "#{f}: #{v.inspect}" }.join(', ')} }" }
+            "One of: #{rows.join('; ')}."
+          else
+            "One of #{value_object.members.flat_map(&:values).uniq.map { |m| "`#{m}`" }.join(', ')}."
+          end
+        elsif value_object.attributes.empty?
+          "A marker with no fields of its own."
+        else
+          "{ #{value_object.attributes.map { |f| "#{f.name}: #{f.type}" }.join(', ')} }"
+        end
+      end
+
+      def command_entries(bluebook, holder_agg)
+        holders(bluebook).flat_map do |holder|
+          holder.commands.map do |command|
+            Entry.new(term: command.hecks_name, kind: "Command", within: holder.hecks_name,
+                      section: holder_agg[holder.hecks_name], definition: command.goal)
+          end
+        end
+      end
+
+      def query_entries(bluebook, holder_agg)
+        holders(bluebook).flat_map do |holder|
+          holder.queries.map do |query|
+            Entry.new(term: query.hecks_name, kind: "Query", within: holder.hecks_name,
+                      section: holder_agg[holder.hecks_name], definition: query.description)
+          end
+        end
+      end
+
+      # CROSS-AGGREGATE, ON PURPOSE — a read model joins heads from more
+      # than one aggregate (`ReadModel`'s own header: "an ask that
+      # gathers heads from more than one aggregate"), so it belongs to
+      # no single one and gets its own trailing section instead.
+      def read_model_entries(bluebook)
+        bluebook.read_models.map do |read_model|
+          Entry.new(term: read_model.name, kind: "Read Model", section: READ_MODELS_SECTION,
+                    definition: read_model.description)
+        end
+      end
+
+      # AN EVENT IS NEVER ITS OWN DECLARATION — the language only ever
+      # spells one as a bare string in a command's `emits:`. So it earns
+      # a glossary entry by appearing there, and its "definition" is the
+      # one fact the graph actually holds about it: which verb(s) raise
+      # it, and — the other half nothing raises without a reader
+      # crossing over to check `bluebook.policies` by hand — which
+      # policy (if any) reacts to it. That is derived, not invented —
+      # nobody wrote a sentence this restates.
+      def event_entries(bluebook, event_agg)
+        by_event = Hash.new { |h, k| h[k] = [] }
+        holders(bluebook).each do |holder|
+          holder.commands.each do |command|
+            command.emits.each { |event| by_event[event] << command.hecks_name }
+          end
+        end
+        by_event.map do |event, commands|
+          sentence = "Raised by #{commands.uniq.map { |c| "`#{c}`" }.join(', ')}."
+          reactions = policies_on(bluebook, event)
+          sentence += " #{reactions.join(' ')}" unless reactions.empty?
+          Entry.new(term: event, kind: "Event", section: event_agg[event], definition: sentence)
+        end
+      end
+
+      # A POLICY NAMES ITS EVENT QUALIFIED (`"Account.AccountFrozen"`) —
+      # `bare` strips the aggregate a policy's own `on_event`/
+      # `trigger_command` always carries but an event's own glossary
+      # term (keyed off `emits:`, which is never qualified) never does.
+      def bare(qualified) = qualified.to_s.split(".").last
+
+      def policies_on(bluebook, event)
+        bluebook.policies.select { |policy| bare(policy.on_event) == event }.map do |policy|
+          domain = " in #{policy.target_domain}" if policy.target_domain
+          "Triggers policy `#{policy.name}` → `#{policy.trigger_command}`#{domain}."
+        end
+      end
+
+      # A ROLE IS THE SAME SHAPE OF FACT AS AN EVENT — free text on a
+      # command's `role:`, never declared on its own — so it gets the
+      # same treatment: who it is, told by what it does. CROSS-CUTTING
+      # BY NATURE (`System`/`Customer` issue commands across half the
+      # aggregates in this corpus), so — like a Read Model — it belongs
+      # to no single aggregate.
+      def role_entries(bluebook)
+        by_role = Hash.new { |h, k| h[k] = [] }
+        holders(bluebook).each do |holder|
+          holder.commands.select(&:role).each { |command| by_role[command.role] << command.hecks_name }
+        end
+        by_role.map do |role, commands|
+          Entry.new(term: role, kind: "Role", section: ROLES_SECTION,
+                    definition: "Issues #{commands.uniq.map { |c| "`#{c}`" }.join(', ')}.")
+        end
+      end
+
+      # A LIFECYCLE HAS NO NAME OF ITS OWN — it is a body nested inside
+      # the aggregate or entity it governs (`lifecycle :status do ...
+      # end`), so it earns a glossary entry under ITS HOLDER's term,
+      # the same way `Command`/`Query` do — a reader who looks up
+      # `Account` and a reader who looks up what states an Account can
+      # hold are asking two different questions of the same name.
+      def lifecycle_entries(bluebook, holder_agg)
+        holders(bluebook).select(&:lifecycle).map do |holder|
+          lifecycle = holder.lifecycle
+          states = ([lifecycle.default] + lifecycle.transitions.map { |_name, transition| transition.target }).uniq
+          Entry.new(term: holder.hecks_name, kind: "Lifecycle", section: holder_agg[holder.hecks_name],
+                    definition: "Starts at `#{lifecycle.default}`. States: #{states.map { |s| "`#{s}`" }.join(', ')}.")
+        end
+      end
+
+      # A SAGA'S OWN HANDLERS/DISPATCHES ARE NAMELESS TOO — the same
+      # shape as a Lifecycle's transitions, one level up: a sequence of
+      # states no individual step is worth its own glossary row for.
+      # `states`, from the builder's own precomputed leg order
+      # (`Behaviour::ProcessManager#saga`, the same field
+      # `DocsProjector#closing` already reads), says what a Lifecycle
+      # entry says for an aggregate — the shape of the whole journey,
+      # not just where it starts and ends. HOMED ON ITS STARTING EVENT —
+      # a saga usually ends somewhere else entirely (that is most of
+      # what makes it a saga), so "where it begins" is the only single
+      # aggregate honestly its own.
+      def saga_entries(bluebook, event_agg)
+        bluebook.process_managers.map do |saga|
+          shape = saga.to_h
+          sentence = "Starts on `#{shape[:starts_on]}`, ends on `#{shape[:ends_on]}`."
+          states = Array(shape[:states])
+          sentence += " States: #{states.map { |s| "`#{s}`" }.join(' → ')}." unless states.empty?
+          Entry.new(term: shape[:name], kind: "Saga", section: event_agg[bare(shape[:starts_on])],
+                    definition: sentence)
+        end
+      end
+
+      # A POLICY IS A NAMED CONSTRUCT TOO (`policy "ReviewOnFreeze" do
+      # ... end`), the same as a Saga — so it earns its own glossary
+      # entry rather than surfacing only as a parenthetical on the
+      # event that triggers it. HOMED ON THE EVENT IT REACTS TO, not
+      # what it dispatches — `on_event` is always local to this
+      # bluebook, `trigger_command` sometimes is not (a cross-domain
+      # policy's own `across`). `for_each`, when declared, fans the
+      # dispatch out over more than one record; stated here because a
+      # reader who only sees "dispatches X" would otherwise assume one.
+      def policy_entries(bluebook, event_agg)
+        bluebook.policies.map do |policy|
+          sentence = "On `#{bare(policy.on_event)}`, dispatches `#{policy.trigger_command}`"
+          sentence += " in #{policy.target_domain}" if policy.target_domain
+          sentence += ", once per `#{policy.for_each}` row" if policy.for_each
+          Entry.new(term: policy.name, kind: "Policy", section: event_agg[bare(policy.on_event)],
+                    definition: "#{sentence}.")
+        end
+      end
+
+      # ── rendering ─────────────────────────────────────────────────────
+
+      def render(bluebook)
+        all = entries(bluebook)
+        grouped = all.reject { |entry| entry.kind == "Domain" }.group_by { |entry| entry.section || "Cross-Domain Reactions" }
+
+        out = [chapter_header(bluebook)]
+        bluebook.aggregates.map(&:hecks_name).sort.each { |name| out << section(name, grouped[name]) if grouped[name] }
+        [ROLES_SECTION, READ_MODELS_SECTION, "Cross-Domain Reactions"].each do |name|
+          out << section(name, grouped[name]) if grouped[name]
+        end
+
+        "#{out.compact.join("\n\n")}\n"
+      end
+
+      def chapter_header(bluebook)
+        out = ["# #{bluebook.name} — Glossary", ""]
+        out += ["> #{bluebook.vision}", ""] if bluebook.vision
+        out << "The ubiquitous language: every term #{bluebook.name} declares, grouped under the aggregate " \
+               "it belongs to, in the domain's own words. Generated from `#{bluebook.name}`'s bluebook — a " \
+               "term missing here is a term the bluebook does not yet declare, and a definition missing here " \
+               "is a sentence nobody has written yet."
+        out.join("\n")
+      end
+
+      def section(title, rows)
+        return nil unless rows
+
+        sorted = rows.sort_by { |entry| [KIND_RANK[entry.kind] || 99, entry.term.downcase] }
+        "## #{title}\n\n| Term | Kind | Definition |\n|---|---|---|\n#{sorted.map { |entry| entry_row(entry) }.join("\n")}"
+      end
+
+      def entry_row(entry)
+        term = entry.within ? "**#{entry.term}** *(#{entry.within})*" : "**#{entry.term}**"
+        "| #{term} | #{entry.kind} | #{entry.definition || '—'} |"
+      end
+    end
+  end
+end

data/lib/hecks/projections/ir.rb

@@ -1,6 +1,8 @@
 require_relative "../projector"
 
 module Hecks
+  # Reopened from projections.rb (see there for the namespace's full
+  # rationale) to define and register the :ir target below.
   module Projections
     # The canonical IR, as a constant. The implementation already existed
     # and is already golden-tested (`Projector::IRProjector`, registered

data/lib/hecks/projections/model/deviations.rb

@@ -60,7 +60,8 @@ module Hecks
           "Bluebook"    => { ir_version:     "the EMISSION's own version, not the domain's",
                              canonical_form: "the normalisation table every reader needs beside the IR" },
           "ValueObject" => { closed_set:     "an empty one_of and no one_of are otherwise indistinguishable" },
-          "Aggregate"   => { ports:          "declared in the hecksagon, attached after the aggregate exists" }
+          "Aggregate"   => { ports:          "declared in the hecksagon, attached after the aggregate exists" },
+          "Policy"      => { where_ast:      "the structured form of `where`, derived from the same text at emission" }
         }.freeze
 
         # DECLARED, AND DELIBERATELY NOT EMITTED. The category that had no

data/lib/hecks/projections/model.rb

@@ -50,7 +50,11 @@ module Hecks
           # a binding that reads an event field and one that supplies a
           # literal string are otherwise indistinguishable once written
           # down (see `MetaValidator::Readings`' own note on exactly that).
-          renders:   { with_spec: "-> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } }" },
+          renders:   { with_spec: "-> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } }",
+                       # COMPUTED (Deviations::COMPUTED["Policy"]): the structured
+                       # form of `where`, a pure function of that text, the same
+                       # `ast` every rule row carries beside its `canonical`.
+                       where_ast: "-> { where_ast }" },
           settles:   false
         }
       }.freeze
@@ -66,7 +70,7 @@ module Hecks
           # GENERATED — projected from the language's own #{name} aggregate.
           # DO NOT EDIT: the holding half is rendered, and #{host.fetch(:behaviour)}
           # is where anything hand-written belongs.
-          require_relative "behaviour/#{File.basename(host.fetch(:file), ".rb")}"
+          require_relative "behaviour/#{File.basename(host.fetch(:file), '.rb')}"
 
           module Hecks
             module Bluebook
@@ -87,14 +91,15 @@ module Hecks
 
       # The emission, keyed as the model spells it and sourced as the
       # language declares it.
+      # A COMPUTED field (Deviations::COMPUTED) is emitted too — it is
+      # model-only by definition, so it rides after the declared fields
+      # and MUST have a `renders` entry, there being nothing to `send`.
       def emits(bluebook, name)
-        fields  = emitted_fields(bluebook, name)
+        fields  = emitted_fields(bluebook, name) + Deviations.computed(name)
         renders = HOST.fetch(name).fetch(:renders, {})
         width   = fields.map { |f| f.to_s.length }.max.to_i
 
-        "emits_ir(\n" +
-          fields.map { |f| "  #{"#{f}:".ljust(width + 1)} #{renders.fetch(f, ":#{f}")}" }.join(",\n") +
-          "\n)"
+        "emits_ir(\n#{fields.map { |f| "  #{"#{f}:".ljust(width + 1)} #{renders.fetch(f, ":#{f}")}" }.join(",\n")}\n)"
       end
 
       # WHAT THE CONSTRUCT EMITS: what the language declares, less every
@@ -121,18 +126,18 @@ module Hecks
         # here rather than typed in — a comment that survives
         # regeneration is one the generator writes.
         reasons = Deviations::OFF_THE_WIRE.fetch(host.fetch(:construct, ""), {})
-        (lines + accessors.map { |a|
+        (lines + accessors.map do |a|
           why = reasons[a]
           (why ? "\n# #{a.upcase}, DECLARED AND DELIBERATELY OFF THE WIRE\n# #{wrap(why)}\n" : "") +
             "attr_accessor :#{a}"
-        }).join("\n")
+        end).join("\n")
       end
 
       def constructor(host)
         args = host.fetch(:defaults).map { |f, d| d ? "#{f}: #{d}" : "#{f}:" }.join(", ")
-        body = host.fetch(:defaults).keys.map { |f|
+        body = host.fetch(:defaults).keys.map do |f|
           "  @#{f} = #{f}#{host.fetch(:coerce, {})[f]}"
-        }
+        end
         body << "\n  settle" if host.fetch(:settles, true)
 
         "def initialize(#{args})\n#{body.join("\n")}\nend"

data/lib/hecks/projections/vocabulary.rb

@@ -58,9 +58,7 @@ module Hecks
 
       def render(bluebook)
         rows = tables(bluebook).sort_by(&:first).map do |name, members|
-          "      #{name.inspect} => [\n" +
-            members.map { |row| "        #{row.inspect}.freeze" }.join(",\n") +
-            "\n      ].freeze"
+          "      #{name.inspect} => [\n#{members.map { |row| "        #{row.inspect}.freeze" }.join(",\n")}\n      ].freeze"
         end
 
         <<~RUBY

data/lib/hecks/projections.rb

@@ -30,3 +30,4 @@ require_relative "projections/reference"
 require_relative "projections/model"
 require_relative "projections/diagrams"
 require_relative "projections/statements"
+require_relative "projections/glossary"

data/lib/hecks/projector/cli_projector.rb

@@ -54,12 +54,12 @@ module Hecks
           aggregate.queries.each  { |q| claim(questions, name_for(aggregate, q), query_spec(bluebook, aggregate, nil, q)) }
 
           aggregate.entities.each do |entity|
-            entity.commands.each { |c|
+            entity.commands.each do |c|
               claim(verbs, name_for(aggregate, c, entity), command_spec(bluebook, aggregate, entity, c))
-            }
-            entity.queries.each { |q|
+            end
+            entity.queries.each do |q|
               claim(questions, name_for(aggregate, q, entity), query_spec(bluebook, aggregate, entity, q))
-            }
+            end
           end
 
           # A PORT IS A VERB TOO, and leaving it off the map was a real gap
@@ -156,6 +156,33 @@ module Hecks
          entity ? "#{entity.hecks_name}." : "", verb.hecks_name].join
       end
 
+      # THE ARGUMENTS A RECEIVER ADDS, BEFORE ANY VERB-SPECIFIC ONE. Shared by
+      # `command_spec` and `port_spec` — a port operation always addresses an
+      # aggregate record (`port_spec` passes `receiver: :aggregate`, never
+      # `:entity` or `nil`, because a port is declared on an aggregate, never
+      # an entity), and this is exactly the same "how do I name the record"
+      # question a command with a receiver already answers, so it is answered
+      # once, here, rather than duplicated.
+      #
+      # `nil` — a creating command — takes none: there is no existing record
+      # yet for `to=` to name.
+      def receiver_options(receiver, aggregate, entity)
+        case receiver
+        when :entity
+          [
+            { path: "to.aggregate", type: "String", required: true,
+              note: "id of the #{aggregate.hecks_name} holding the #{entity.hecks_name}" },
+            { path: "to.entity", type: "String", required: true,
+              note: "id of the #{entity.hecks_name} to act on" }
+          ]
+        when :aggregate
+          [{ path: "to", type: "String", required: true,
+             note: "id of the #{aggregate.hecks_name} to act on" }]
+        else
+          []
+        end
+      end
+
       # ── one verb ──────────────────────────────────────────────────────
 
       def command_spec(bluebook, aggregate, entity, command)
@@ -166,7 +193,6 @@ module Hecks
                     else
                       (command.creates? ? nil : :aggregate)
                     end
-        legacy_arguments = []
 
         # THE RECEIVER IS NOT A COMMAND ARGUMENT. An aggregate command names
         # its record through to; an entity command needs both the aggregate
@@ -178,18 +204,8 @@ module Hecks
         # Existing aggregate scripts may still spell the receiver id=... .
         # That alias is deliberately hidden from help and recorded separately
         # as legacy_arguments; new help and examples teach only to=... .
-        if entity
-          arguments = [
-            { path: "to.aggregate", type: "String", required: true,
-              note: "id of the #{aggregate.hecks_name} holding the #{entity.hecks_name}" },
-            { path: "to.entity", type: "String", required: true,
-              note: "id of the #{entity.hecks_name} to act on" }
-          ] + arguments
-        elsif receiver == :aggregate
-          arguments = [{ path: "to", type: "String", required: true,
-                         note: "id of the #{aggregate.hecks_name} to act on" }] + arguments
-          legacy_arguments = [{ path: "id", type: "String", required: true }]
-        end
+        arguments = receiver_options(receiver, aggregate, entity) + arguments
+        legacy_arguments = receiver == :aggregate ? [{ path: "id", type: "String", required: true }] : []
 
         { verb: fqn(bluebook, aggregate, command, entity), kind: :command,
           summary: command.goal, role: command.role, role_gated: !command.role.to_s.empty?,
@@ -235,7 +251,11 @@ module Hecks
           # `CommandInterpreter`/`EntityInterpreter` call it, never the port
           # dispatch path), so `role_gated: false` always, unlike
           # `command_spec` where the same key name means a real one.
-          role: operation.outbound? ? "#{aggregate.hecks_name} asking #{port.name}" : "#{port.name} telling #{aggregate.hecks_name}",
+          role: if operation.outbound?
+                  "#{aggregate.hecks_name} asking #{port.name}"
+                else
+                  "#{port.name} telling #{aggregate.hecks_name}"
+                end,
           role_gated: false,
           summary: port_summary(port, operation), arguments: arguments }
       end
@@ -289,8 +309,8 @@ module Hecks
       # malformed records into a real store, which is what it did on its first
       # run against the pizzas database.
       def options_for(attribute, holder, aggregate, prefix = nil, optional = nil)
-        path     = [prefix, attribute.name].compact.join(".")
-        optional = optional || attribute.optional?
+        path = [prefix, attribute.name].compact.join(".")
+        optional ||= attribute.optional?
         return [reference_option(attribute)] if attribute.reference?
 
         value_object = value_object_for(attribute, holder, aggregate)
@@ -408,38 +428,54 @@ module Hecks
         text.to_s.split(/(?<=\.)\s/).first.to_s
       end
 
+      # FOUR TEXT BLOCKS, IN FIXED DISPLAY ORDER — meta (name/kind/role),
+      # invocation, arguments, refusals. Each block is independent of the
+      # others' content (only the OUTPUT ORDER is fixed, and stays fixed
+      # below), so each is its own method returning the lines it
+      # contributes — `[]` when it contributes none — concatenated in the
+      # same order the original inline version built them in.
       def verb_help(program, name, spec, ask: false)
+        out = verb_help_meta_lines(name, spec)
+        out.concat(verb_help_invocation_lines(program, name, spec, ask))
+        out.concat(verb_help_argument_lines(spec))
+        out.concat(verb_help_refusal_lines(spec))
+        out.join("\n")
+      end
+
+      def verb_help_meta_lines(name, spec)
         out = ["#{name} — #{spec[:summary]}", ""]
         out << "dispatches #{spec[:verb]}" if spec[:kind] == :command
         out << "reads #{spec[:verb]}"      if spec[:kind] == :query
         out << "issued by #{spec[:role]}"  if spec[:role]
-        out << ""
+        out
+      end
+
+      def verb_help_invocation_lines(program, name, spec, ask)
         invocation = ask ? "#{program} ask #{name}" : "#{program} #{name}"
-        out << "  #{invocation}#{spec[:arguments].map { |a| " #{a[:path]}=…" }.join}"
-        out << ""
+        ["", "  #{invocation}#{spec[:arguments].map { |a| " #{a[:path]}=…" }.join}", ""]
+      end
 
-        unless spec[:arguments].empty?
-          width = spec[:arguments].map { |a| a[:path].length }.max
-          spec[:arguments].each do |argument|
-            notes = []
-            notes << argument[:type]
-            notes << "one of #{argument[:enum].join(', ')}" if argument[:enum]
-            notes << "matches #{argument[:pattern]}"        if argument[:pattern]
-            notes << "defaults to #{argument[:default].inspect}" unless argument[:default].nil?
-            notes << argument[:note]                        if argument[:note]
-            notes << "optional"                             unless argument[:required]
-            out << "  #{argument[:path].ljust(width)}  #{notes.join('; ')}"
-          end
-          out << ""
+      def verb_help_argument_lines(spec)
+        return [] if spec[:arguments].empty?
+
+        width = spec[:arguments].map { |a| a[:path].length }.max
+        lines = spec[:arguments].map do |argument|
+          notes = []
+          notes << argument[:type]
+          notes << "one of #{argument[:enum].join(', ')}" if argument[:enum]
+          notes << "matches #{argument[:pattern]}"        if argument[:pattern]
+          notes << "defaults to #{argument[:default].inspect}" unless argument[:default].nil?
+          notes << argument[:note]                        if argument[:note]
+          notes << "optional"                             unless argument[:required]
+          "  #{argument[:path].ljust(width)}  #{notes.join('; ')}"
         end
+        lines << ""
+      end
 
-        unless Array(spec[:refusals]).empty?
-          out << "refused when:"
-          spec[:refusals].each { |refusal| out << "  #{refusal}" }
-          out << ""
-        end
+      def verb_help_refusal_lines(spec)
+        return [] if Array(spec[:refusals]).empty?
 
-        out.join("\n")
+        ["refused when:", *spec[:refusals].map { |refusal| "  #{refusal}" }, ""]
       end
     end
   end