hecks 2.7.0 → 2.9.0

data/lib/hecks/facade/cli_door.rb

@@ -2,57 +2,31 @@ require_relative "../runtime/errors"
 
 module Hecks
   module Facade
-    # **The CLI door** — where Facade meets a caller holding flat strings.
-    #
-    # `JsonDoor` beside this one translates for a caller holding parsed JSON:
-    # String keys, already-nested objects, real Integers. A command line has
-    # neither of those. It has `sequence.value=99` — one flat string, with the
-    # nesting spelled as a path and the type not spelled at all.
-    #
-    # So this does the two things that turns into: rebuild the nesting, and
-    # give every leaf the type the chapter declared for it.
-    #
-    # The type comes from the projection, never from the value. A door that
-    # guessed — "99 looks like a number" — would send the Integer 99 for a
-    # version string of "99", and be wrong in a way nothing downstream could
-    # detect, because both are perfectly good arguments. `Projector::CliProjector`
-    # already read the declared field type out of the value object; this only
-    # applies it.
+    # Turns `path=value` command-line words into a nested, typed argument Hash.
+    # Types come from the projection, never from guessing at the value ("99" may be a String).
     module CliDoor
       module_function
 
-      # Builds a verb's nested, typed argument Hash out of the `name=value` words on a
-      # command line.
+      # Builds a verb's nested, typed argument Hash from its `name=value` words.
       #
-      # `["reference.value=BUG#1", "sequence.value=99"]` against a projected
-      # verb spec -> `{ reference: { value: "BUG#1" }, sequence: { value: 99 } }`
+      #   arguments(spec, ["reference.value=A-1", "sequence.value=99"])
+      #   # => { reference: { value: "A-1" }, sequence: { value: 99 } }
       #
-      # @param spec [Hash{Symbol => Object}] one verb's entry from `Projector::CliProjector`;
-      #   read for `:arguments` and the optional `:legacy_arguments`, each an Array of
-      #   option Hashes with `:path`, `:type` and, for a list, `:list`
-      # @param pairs [Array<String>] the words after the verb, each `path=value`; a path
-      #   may be the short form of a single-field value object (`reference` for
-      #   `reference.value`)
-      # @return [Hash{Symbol => Object}] the arguments nested by path, each leaf cast to
-      #   its declared type and each list option collected into an Array; `{}` for no pairs
-      # @raise [Runtime::NotFound] if a pair has no `=`, or names a path the verb does
-      #   not take
-      # @raise [Runtime::TypeMismatch] if a value cannot be read as the declared Integer
-      #   or Float
+      # @param spec [Hash{Symbol => Object}] one verb's entry from `Projector::CliProjector`
+      # @param pairs [Array<String>] the words after the verb; a path may be the short form
+      #   of a single-field value object (`reference` for `reference.value`)
+      # @return [Hash{Symbol => Object}] the arguments nested by path, leaves cast to type
+      # @raise [Runtime::NotFound] if a pair has no `=` or names a path the verb lacks
+      # @raise [Runtime::TypeMismatch] if a value does not parse as its Integer or Float
       def arguments(spec, pairs)
-        # Legacy options are accepted but not printed in help. This lets an
-        # existing id=... aggregate invocation cross the new receiver boundary
-        # while the projected surface teaches to=... exclusively.
+        # Extra accepted arguments stay out of help, which teaches only to=....
         options = (spec[:arguments] + Array(spec[:legacy_arguments])).to_h do |argument|
           [argument[:path], argument]
         end
 
         pairs.each_with_object({}) do |pair, args|
           path, value = split(pair)
-          # key? first, never `||` — full names whichever spelling (the
-          # bare path, or its one-argument expansion) actually declares
-          # this option, and the lookup below must hold to that same
-          # decision rather than re-guessing which one exists.
+          # key? rather than `||`, so the lookup below honors the same spelling `full` chose.
           full     = options.key?(path) ? path : expand(path, options)
           argument = options.key?(full) ? options[full] : raise(Runtime::NotFound, unknown(path, options.keys))
 
@@ -62,12 +36,7 @@ module Hecks
         end
       end
 
-      # Cuts one command-line word at its first `=`, so a value may itself contain `=`.
-      #
-      # @param pair [String] one word, such as `"reference.value=BUG#1"`
-      # @return [Array(String, String)] the path and the value; the value is `""` for
-      #   `"name="`
-      # @raise [Runtime::NotFound] if the word contains no `=`
+      # Cuts one word at its first `=`, so a value may itself contain `=`.
       def split(pair)
         name, value = pair.split("=", 2)
         raise Runtime::NotFound, "#{pair.inspect} is not name=value" if value.nil?
@@ -75,32 +44,15 @@ module Hecks
         [name, value]
       end
 
-      # Expands a bare value-object name into the full path of its only field.
-      #
-      # The short form, for the common case. Almost every value object in this
-      # corpus has exactly one field, so `reference=BUG#1` is unambiguous and
-      # is what anybody types. Expanded only when precisely one option starts
-      # with that prefix — two would be a guess, and a guess about which field
-      # a caller meant is worse than asking them to say.
-      #
-      # @param path [String] the path as typed, such as `"reference"`
-      # @param options [Hash{String => Hash}] the verb's options keyed by full path
-      # @return [String] the one full path beginning `"#{path}."`, or `path` unchanged when
-      #   none or several do
+      # Expands a bare value-object name into the path of its only field.
+      # Left unchanged when several fields match, since guessing which was meant is worse.
       def expand(path, options)
         candidates = options.keys.select { |key| key.start_with?("#{path}.") }
         candidates.length == 1 ? candidates.first : path
       end
 
-      # Converts one command-line value to the type the chapter declares for its field.
-      #
-      # @param value [String] the text after the `=`
-      # @param type [String] the declared type name; `"Integer"`, `"Float"` and
-      #   `"Boolean"` are converted, anything else leaves the value a String
-      # @return [Integer, Float, Boolean, String] the typed value; a Boolean is true only
-      #   for `true`, `yes` or `1` in any letter case, and false for every other text
-      # @raise [Runtime::TypeMismatch] if the text does not parse as the declared Integer
-      #   or Float
+      # Converts one value to its declared type; only Integer, Float and Boolean convert.
+      # A Boolean is true only for `true`, `yes` or `1` in any letter case.
       def cast(value, type)
         case type
         when "Integer" then Integer(value)
@@ -112,36 +64,12 @@ module Hecks
         raise Runtime::TypeMismatch, "#{value.inspect} is not #{type} — the chapter declares this field as #{type}"
       end
 
-      # Adds one element to a list argument, creating the list on first use.
-      #
-      # A list grows rather than overwrites, and getting this wrong is silent.
+      # Appends one element to a list argument, creating the list on first use.
       #
-      # `tags.value=framework tags.value=model-checker` sent through `bury`
-      # twice would store the second one alone — no refusal, no warning, one tag
-      # simply gone. That is the failure the interview named first: not the
-      # loud kind, the kind where a value is forgotten and the caller has no
-      # way to notice.
-      #
-      # A list of one is still a list. `tags.value=flaky` produces
-      # `[{ value: "flaky" }]`, not `{ value: "flaky" }`, because the chapter
-      # declared a collection and a caller who sent one element did not
-      # thereby declare a different shape. A bare object must never reach a
-      # `list_of` attribute: everything downstream that walks
-      # it — a query's `contains`, a projection, the Postgres adapter's own
-      # array handling — is entitled to assume it can iterate.
-      #
-      # Multi-field elements are not supported here, deliberately. A flat
-      # command line has no way to say which `a.x=` goes with which `a.y=`,
-      # and inventing an index syntax would be a language nobody asked for.
-      # Every list in this corpus is a list of single-field value objects; a
-      # richer one is a job for `JsonDoor`, which has real nesting.
-      #
-      # @param hash [Hash{Symbol => Object}] the arguments built so far; mutated in place
-      # @param path [Array<String>] the option's path segments, at least two: the last
-      #   names the element's field, the one before it names the list
-      # @param value [Integer, Float, Boolean, String] the cast value for the new element
-      # @return [Hash{Symbol => Object}] `hash`, with `{ leaf => value }` appended to the
-      #   Array at the list's key
+      # Repeats must grow the list (`bury` would silently keep only the last), and a single
+      # element is still a one-item list, since a `list_of` attribute must never see a bare
+      # object. Multi-field elements are left to `JsonDoor`: a flat command line cannot say
+      # which `a.x=` pairs with which `a.y=`.
       def append(hash, path, value)
         *branches, leaf = path.map(&:to_sym)
         holder = branches[0..-2].reduce(hash) { |node, key| node[key] ||= {} }
@@ -151,13 +79,7 @@ module Hecks
         hash
       end
 
-      # Sets one value at a nested path, creating each intermediate Hash on the way and
-      # overwriting whatever the leaf already held.
-      #
-      # @param hash [Hash{Symbol => Object}] the arguments built so far; mutated in place
-      # @param path [Array<String>] the option's path segments, outermost first
-      # @param value [Integer, Float, Boolean, String] the cast value to store at the leaf
-      # @return [Hash{Symbol => Object}] `hash`, with the value set under Symbol keys
+      # Sets one value at a nested path, creating intermediate Hashes and overwriting the leaf.
       def bury(hash, path, value)
         *branches, leaf = path.map(&:to_sym)
         target = branches.reduce(hash) { |node, key| node[key] ||= {} }
@@ -166,10 +88,6 @@ module Hecks
       end
 
       # Words the refusal for an argument the verb does not take, listing what it does.
-      #
-      # @param path [String] the path as the caller typed it
-      # @param known [Array<String>] every path the verb accepts, in any order
-      # @return [String] a one-line message naming `path` and the sorted accepted paths
       def unknown(path, known)
         "no argument #{path.inspect} — this verb takes #{known.sort.join(', ')}"
       end

data/lib/hecks/facade/cli_runner.rb

@@ -7,44 +7,21 @@ require_relative "../ports/clock"
 
 module Hecks
   module Facade
-    # The runner behind a projected CLI.
-    #
-    # `Projector::CliProjector` answers what a domain's command line looks
-    # like; this is the twenty lines that parse against it and dispatch. It
-    # lives in `lib/` rather than in a `bin/` because more than one front door
-    # wants it — `bin/run` for whichever domain you are standing in, `bin/qc`
-    # pinned to the QA ledger — and a second copy of the parse-and-dispatch
-    # would be the exact duplication the projection exists to avoid.
-    #
-    # No IO. It answers `[text, status]` and never prints or exits, so a spec
-    # can call it without capturing streams or trapping SystemExit. The `bin/`
-    # scripts do the printing, the same division `Router` and `JsonDoor`
-    # already keep against HTTP.
+    # Parses and dispatches a command line against a `Projector::CliProjector` projection.
+    # Does no IO: it answers `[text, status]` and leaves printing and exiting to `bin/` scripts.
     module CliRunner
       module_function
 
-      # Runs one command line against a booted domain: resolves the verb or question,
-      # parses its `name=value` arguments, dispatches or queries, and answers with the text
-      # to print.
+      # Runs one command line against a booted domain and answers the text to print.
+      # Only the first bluebook in the registry, the booted domain's own, is projected.
       #
-      # `[text, status]` — status 0 answered, 1 refused or misused.
-      #
-      # Only the first bluebook in the registry (the booted domain's own) is projected
-      # into verbs. `--help`, `-h`, `help` or an empty `argv` answers the usage text; a
-      # verb followed by `--help` answers that verb's help.
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain,
-      #   as `Hecks.boot` returns it
-      # @param argv [Array<String>] the words after the program name: an optional `ask`,
-      #   the verb or question name (bare or aggregate-qualified), then `path=value` pairs
+      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
+      # @param argv [Array<String>] an optional `ask`, the verb or question name, then
+      #   `path=value` pairs; `--help`, `-h`, `help` or nothing answers usage
       # @param program [String] how the caller was invoked, echoed in usage and hints
-      # @return [Array(String, Integer)] the text to print and the exit status: 0 with
-      #   usage, help, or pretty-printed JSON of the outcome; 1 with a message when the
-      #   verb is unknown, an argument is wrong, a record is missing, or the domain refuses
-      # @raise [Runtime::WiringError] if a repository, or the clock adapter a `now`
-      #   argument needs, cannot be resolved
-      # @raise [Runtime::StaleWrite] if concurrent writers beat the command through every
-      #   retry
+      # @return [Array(String, Integer)] the text and the status: 0 answered, 1 refused or misused
+      # @raise [Runtime::WiringError] if a repository or the clock adapter cannot be resolved
+      # @raise [Runtime::StaleWrite] if concurrent writers beat the command through every retry
       def call(runtime:, argv:, program: "bin/run")
         bluebook = runtime.registry.bluebooks.values.first
         cli      = Projector.call(:cli, bluebook: bluebook, options: { program: program })
@@ -52,16 +29,14 @@ module Hecks
         name = argv.first
         return [cli[:usage], 0] if name.nil? || %w[--help -h help].include?(name)
 
-        # `ask` puts a question in its own namespace — a chapter may declare a
-        # command and a query of one name, and banking does.
+        # `ask` gives questions their own namespace; a chapter may declare a command and query
+        # of one name.
         asking = name == "ask"
         argv   = argv[1..] if asking
         name   = argv.first
         return [cli[:usage], 1] if name.nil?
 
-        # Resolved through the alias map, so `pizzas create_pizza` and
-        # `pizzas order.create_pizza` reach the same verb — the aggregate is
-        # worth typing only when two of them declare the same word.
+        # The alias map lets `create_pizza` and `order.create_pizza` reach the same verb.
         pool = asking ? cli[:questions] : cli[:verbs]
         key  = cli[:names][asking ? :question : :command][name]
         spec = pool[key]
@@ -77,26 +52,8 @@ module Hecks
         dispatch(runtime, spec, name, rest, program, asking)
       end
 
-      # Parses one resolved verb's arguments, runs it as a query or a command, and turns
-      # the outcome, or the domain's refusal, into printable text.
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain
-      # @param spec [Hash{Symbol => Object}] the verb's entry from `Projector::CliProjector`;
-      #   read for `:kind`, `:verb`, `:arguments`, `:receiver` and `:legacy_receiver`
-      # @param name [String] the verb as the caller typed it, echoed in the `--help` hint
-      # @param rest [Array<String>] the `path=value` words after the verb
-      # @param program [String] how the caller was invoked, echoed in the `--help` hint
-      # @param asking [Boolean] whether the verb was reached through `ask`, which only
-      #   changes the wording of the hint
-      # @return [Array(String, Integer)] status 0 with pretty-printed JSON: the materialized
-      #   rows for a query; `id`, `state` and event names for a command; `id` and events
-      #   with payloads for a port operation. Status 1 with the message of a
-      #   `Runtime::DOMAIN_REFUSALS` error, followed by a `--help` hint when it is a
-      #   `Runtime::NotFound` or `Runtime::TypeMismatch`
-      # @raise [Runtime::WiringError] if a repository, or the clock adapter a `now`
-      #   argument needs, cannot be resolved
-      # @raise [Runtime::StaleWrite] if concurrent writers beat the command through every
-      #   retry
+      # Parses one resolved verb's arguments, runs it as a query or command, and turns the
+      # outcome, or the domain's refusal, into `[json_or_message, status]`.
       def dispatch(runtime, spec, name, rest, program, asking)
         args = stamp_time(runtime, spec, CliDoor.arguments(spec, rest))
 
@@ -105,10 +62,7 @@ module Hecks
           return [JSON.pretty_generate(rows.map { |row| JsonDoor.materialize(row) }), 0]
         end
 
-        # The answer is scoped to what was asked. `bin/run`'s step-list form
-        # reports the whole store because a corpus run is judged on all of it;
-        # somebody who issued one verb wants that verb's outcome, and against a
-        # Postgres-backed domain the full dump is every record there has been.
+        # Answers with only this verb's outcome; a full store dump is every record there is.
         request = CommandRequest.normalize(args, receiver:        spec[:receiver],
                                                  legacy_receiver: spec[:legacy_receiver])
         handle = runtime.dispatch_flat(spec[:verb], request)
@@ -118,62 +72,17 @@ module Hecks
                               state:  JsonDoor.materialize(handle.state),
                               events: handle.events.map(&:name)), 0]
       rescue Runtime::NotFound, Runtime::TypeMismatch => e
-        # A bad argument and a missing record both land here, and both want the
-        # same next step: read what the verb actually takes.
+        # A bad argument and a missing record both need the same next step: read the help.
         ["#{e.message}\n\n  #{program} #{'ask ' if asking}#{name} --help", 1]
       rescue *Runtime::DOMAIN_REFUSALS => e
-        # **The refusal is the product** — the chapter's own sentence, verbatim.
+        # The refusal is the chapter's own sentence, verbatim.
         [e.message, 1]
       end
 
-      # Supplies the current time for a verb that takes a `now` argument the caller left out.
-      #
-      # The clock, filled in at the door.
-      #
-      # A staleness rule needs the time, and the sublanguage cannot ask for it
-      # — a `given` that read the clock would judge the same record differently
-      # on two runs, and every replay, audit and fuzz oracle here assumes it
-      # does not. So `now` stays an argument the predicate merely reads, and
-      # the question becomes who types it. Left to the caller, that is:
-      #
-      #   qa/quality_control target.claim id=QC held_by.value=me \
-      #     now.value=$(date +%s) window.value=900
-      #
-      # which is a shell incantation in front of every claim, and one an agent
-      # gets wrong by pasting a stale number.
-      #
-      # At the door, not in the runtime, and the distinction is load-bearing.
-      # `Ports::IdentityGeneration` reasons the same question through for a
-      # minted uuid and lands on "the value is baked into the caller's args at
-      # the first live dispatch". A clock consulted inside the interpreter
-      # would not have that property — a recorded corpus step replayed
-      # tomorrow would quietly get tomorrow's time, and the fuzzer's oracle and
-      # the adapter-agreement gate both compare runs of exactly that shape. Here
-      # it fills only what a person or an agent is typing, and `runtime.dispatch`
-      # is left alone.
+      # Fills in a `now` argument the caller left out, from the clock port; an explicit one wins.
       #
-      # An explicit value always wins, so a spec or a caller reproducing a
-      # moment says so and is believed. This only supplies what was omitted.
-      #
-      # By name, which is the one uncomfortable part. `now` is a plausible
-      # domain word and nothing declares that it means the clock. It is
-      # tolerable because this is a convenience layer rather than semantics —
-      # the verb's own help says the argument exists, dispatch is unchanged,
-      # and passing it explicitly is always available. The honest version is a
-      # declaration in the chapter (`attribute :now, Instant, from: :clock`),
-      # which is a language change: DSL, IR, the self-hosted grammar and its
-      # goldens. Worth doing; not worth smuggling in here.
-      #
-      # @param runtime [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted domain,
-      #   whose registry names the clock adapter
-      # @param spec [Hash{Symbol => Object}] the verb's projected entry; only an option whose
-      #   `:path` starts `"now."` makes this method act
-      # @param args [Hash{Symbol => Object}] the parsed arguments; not mutated
-      # @return [Hash{Symbol => Object}] `args` itself when the verb takes no `now` or the
-      #   caller gave one; otherwise a copy with `now: { value: seconds }`, the clock port's
-      #   current time in whole seconds
-      # @raise [Runtime::WiringError] if the time is needed and zero or several adapters
-      #   implement the clock port
+      # Done at the door, not in the runtime: a clock read inside the interpreter would give a
+      # replayed corpus step the replay day's time. Matched by the argument's name alone.
       def stamp_time(runtime, spec, args)
         return args unless spec[:arguments].any? { |argument| argument[:path].start_with?("now.") }
         return args if args.key?(:now)
@@ -181,69 +90,22 @@ module Hecks
         args.merge(now: { value: Ports::Clock.now(runtime.registry) })
       end
 
-      # Shapes a port operation's outcome for printing: the record asked about, and each
-      # event with its full payload.
-      #
-      # A port operation has no state, and its payload is the entire point.
-      #
-      # A command answers with the record it changed, so naming the events is
-      # enough — the interesting part is in `state`. A port operation changes
-      # no record: it asked something outside and came back with what was
-      # said, and that lives only in the event payload. Reporting names alone
-      # would print `SpecsCompleted` and drop the spec output on the floor.
-      #
-      # This is what makes a projected CLI usable as somebody's only door. An
-      # agent that may not shell out cannot run `rspec` and read the terminal;
-      # it asks the port and reads the answer, and if the answer is a bare
-      # event name then the door leads nowhere and it needs a shell after all.
+      # Shapes a port operation's outcome, which has no state: each event with its full payload.
       #
-      # Both endings come back the same way, and the status stays 0 for both.
-      # A refusal here is not a misuse — `IssueStillOpen` and `SuiteFailed`
-      # are answers the caller asked for, correctly delivered. Exit 1 is for
-      # "you typed something wrong", and conflating the two would have a
-      # scripted agent treat a healthy no as a broken call.
-      #
-      # @param handle [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result] the
-      #   dispatch result, which for a port operation has a nil `state`
-      # @return [Hash{Symbol => Object}] `:id`, the result's id or else the first event's
-      #   (nil when there is neither), and `:events`, an Array of `{ name:, payload: }`
-      #   Hashes with each payload materialized to plain data
+      # The answer lives only in the payloads, so names alone would drop it. Exit status stays 0
+      # for refusal events too, since a healthy no is an answer, not a misuse.
       def answered(handle)
-        # The ID comes off the event, because a port operation hydrates no
-        # instance and the handle's own `id` is nil by design. The event knows
-        # which record was asked about — it was stamped with it — and printing
-        # `null` beside a payload that plainly says `SW-TOOL` would read as a
-        # bug in something.
+        # A port operation hydrates no instance, so the handle's `id` is nil by design.
         { id:     handle.id || handle.events.first&.id,
           events: handle.events.map do |event|
             { name: event.name, payload: JsonDoor.materialize(event.payload) }
           end }
       end
 
-      # Words the answer to a verb or question that does not exist, suggesting up to five
-      # names that start the same way.
-      #
-      # A near miss is worth more than a list. Somebody who typed
-      # `bug.discovr` wants one line, not eighty-seven of them.
-      #
-      # Ranked by shared prefix, not by substring. Substring matching finds
-      # nothing for the commonest typo of all — a dropped
-      # letter, `order.create_piza`, which is a substring of nothing. Prefix
-      # length survives an error anywhere after it, which is where errors are.
-      #
-      # @param cli [Hash{Symbol => Object}] the `Projector::CliProjector` projection; read
-      #   for `cli[:names]`, the alias maps under `:command` and `:question`
-      # @param name [String] what the caller typed
-      # @param asking [Boolean] whether it was typed after `ask`, which picks the question
-      #   names and the wording
-      # @param program [String] how the caller was invoked, echoed in the closing hint
-      # @return [String] a multi-line message; candidates must share a prefix of at least
-      #   half of `name`'s length, and never fewer than three characters
+      # Words the answer for an unknown verb or question, suggesting up to five near names.
+      # Ranked by shared prefix, which survives a dropped letter where a substring match would not.
       def unknown(cli, name, asking, program)
-        # **Both spellings are candidates**. A caller who typed the qualified
-        # form with a typo — `order.create_piza` — shares no prefix with the
-        # short name `create_pizza`, so pooling only one of them suggests
-        # nothing for half the mistakes anybody makes.
+        # Both spellings are candidates: `order.create_piza` shares no prefix with `create_pizza`.
         pool = cli[:names][asking ? :question : :command].keys
         near = pool.map    { |candidate| [shared_prefix(candidate, name), candidate] }
                    .select { |shared, _| shared >= [name.length / 2, 3].max }
@@ -256,12 +118,6 @@ module Hecks
         lines.join("\n")
       end
 
-      # Counts how many leading characters two names have in common.
-      #
-      # @param one [String] a candidate name
-      # @param other [String] the name to compare it with
-      # @return [Integer] the length of the common prefix, from 0 up to the shorter
-      #   name's length
       def shared_prefix(one, other)
         length = [one.length, other.length].min
         (0...length).find { |index| one[index] != other[index] } || length

data/lib/hecks/facade/command_request.rb

@@ -2,42 +2,24 @@ require_relative "../runtime/errors"
 
 module Hecks
   module Facade
-    # Turns an external command request into the dispatcher's receiver/payload
-    # envelope. Human-facing doors may accept their old flat id spelling at
-    # the edge, but every call leaving this boundary has one shape:
+    # Turns an external command request into the dispatcher's `to:`/`with:` envelope.
     #
     #   aggregate command: { to: "record-id", with: { declared: "facts" } }
-    #   entity command:    { to: { aggregate: "...", entity: "..." },
-    #                        with: { declared: "facts" } }
-    #
-    # The command interpreter remains the authority on which facts are
-    # declared. This helper only prevents routing fields from leaking into the
-    # fact payload and gives every external door the same wire contract.
+    #   entity command:    { to: { aggregate: "...", entity: "..." }, with: { ... } }
     module CommandRequest
       module_function
 
-      # Splits one external request into routing (`to:`) and facts (`with:`), accepting
-      # either the explicit envelope or a flat Hash, and refuses a receiver that does
-      # not fit the kind of command being called.
-      #
-      # Keys are symbolized at every depth first, so a parsed JSON body and a Ruby Hash
-      # are treated alike. In a flat Hash everything but `to` (or the legacy receiver
-      # keys) is a fact.
+      # Splits a request, explicit envelope or flat Hash, into routing (`to:`) and facts (`with:`).
+      # Keys are symbolized at every depth; in a flat Hash everything but the receiver is a fact.
       #
-      # @param input [Hash, Object] the request, with String or Symbol keys; anything
-      #   that is not a Hash is refused
-      # @param receiver [Symbol, nil] the kind of receiver the command takes:
-      #   `:aggregate` (an identity), `:entity` (a Hash of `aggregate:` and `entity:`
-      #   identities), or `nil` for a command that takes none, such as a creating command
-      # @param legacy_receiver [Symbol, String, Hash{Symbol => Symbol, String}, nil] where
-      #   a flat request without `to` may carry its receiver instead: one key name (such
-      #   as `:id`) for an `:aggregate` receiver, or `{ aggregate: key, entity: key }` for
-      #   an `:entity` receiver; `nil` accepts no legacy spelling
-      # @return [Hash{Symbol => Object}] `{ with: facts }`, plus `to:` holding the route
-      #   whenever `receiver` is not `nil`; ready to pass to `Dispatcher#dispatch_flat`
-      # @raise [Runtime::TypeMismatch] if `input` or its `with:` is not a Hash, if an
-      #   explicit envelope carries keys other than `to:` and `with:`, or if the route
-      #   is missing, blank, malformed, or given to a command that takes no receiver
+      # @param input [Hash] the request, with String or Symbol keys
+      # @param receiver [Symbol, nil] `:aggregate`, `:entity`, or `nil` for a command with none
+      # @param legacy_receiver [Symbol, String, Hash, nil] the flat key that may carry the
+      #   receiver instead of `to:`: a name for `:aggregate`, `{ aggregate:, entity: }` for
+      #   `:entity`
+      # @return [Hash{Symbol => Object}] `{ with: facts }`, plus `to:` when `receiver` is set
+      # @raise [Runtime::TypeMismatch] if the request is malformed or the route does not fit
+      #   the receiver kind
       # @raise [ArgumentError] if `receiver` is not `nil`, `:aggregate` or `:entity`
       def normalize(input, receiver:, legacy_receiver: nil)
         request = symbolize(input)
@@ -87,9 +69,7 @@ module Hecks
       end
       private_class_method :take_legacy_route
 
-      # A case dispatch over the three closed receiver kinds (nil,
-      # :aggregate, :entity) plus the impossible-kind backstop — each
-      # branch is its own self-contained validation for that one kind.
+      # One self-contained check per closed receiver kind, plus a backstop.
       # rubocop:disable-next Metrics/CyclomaticComplexity
       def validate_route!(route, receiver)
         case receiver