hecks 2.8.0 → 3.0.0

data/lib/hecks/doors/cli_door.rb

@@ -0,0 +1,196 @@
+require_relative "../runtime/errors"
+
+module Hecks
+  module Doors
+    # 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
+      # The words a Boolean is spelled with, and what each means.
+      BOOLEAN_WORDS = { "true" => true, "yes" => true, "1" => true, "on" => true,
+                        "false" => false, "no" => false, "0" => false, "off" => false }.freeze
+
+      module_function
+
+      # Builds a verb's nested, typed argument Hash from its `name=value` words.
+      #
+      #   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`
+      # @param pairs [Array<String>] the words after the verb: `name=value` pairs, where a path may
+      #   be the short form of a single-field value object (`reference` for `reference.value`);
+      #   `--name` for a Boolean; and at most one bare word, which fills the verb's first argument
+      # @return [Hash{Symbol => Object}] the arguments nested by path, leaves cast to type
+      # @raise [Runtime::NotFound] if a path, flag or bare word does not fit the verb
+      # @raise [Runtime::TypeMismatch] if a value does not parse as its Integer or Float
+      def arguments(spec, pairs)
+        # 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
+
+        normalize(spec, pairs, options).each_with_object({}) do |pair, args|
+          path, value = split(pair)
+          # 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))
+
+          next words(args, full.split("."), value, argument[:type]) if argument[:words]
+          next append(args, full.split("."), cast(value, argument[:type])) if argument[:list]
+
+          bury(args, full.split("."), cast(value, argument[:type]))
+        end
+      end
+
+      # Rewrites the short forms into `name=value`: `--name` for a Boolean (a following `yes`,
+      # `no`, `true`, `false`, `on`, `off`, `1` or `0` is that flag's value, not an argument),
+      # `--name=value` as `name=value`, and one bare word as the verb's first argument (`to` for
+      # a command on an existing aggregate, the first attribute for one that creates).
+      def normalize(spec, words, options)
+        queue = words.dup
+        pairs = []
+        bare  = []
+        until queue.empty?
+          word = queue.shift
+          if word.start_with?("--") && word.include?("=")
+            pairs << underscored(word.delete_prefix("--"), options)
+          elsif word.start_with?("--")
+            path  = flag(word.delete_prefix("--"), options)
+            value = BOOLEAN_WORDS.key?(queue.first.to_s.downcase) ? queue.shift : "true"
+            pairs << "#{path}=#{value}"
+          elsif word.include?("=")
+            pairs << word
+          else
+            bare << word
+            pairs << word
+          end
+        end
+        raise Runtime::NotFound, too_many_bare(bare) if bare.length > 1
+
+        pairs.map { |pair| bare.include?(pair) && !pair.include?("=") ? positional(pair, spec) : pair }
+      end
+
+      # A `name=value` pair whose name is spelled with dashes (`seed-start=3`), as the argument
+      # spelled with underscores, unless an argument is named with the dashes.
+      def underscored(pair, options)
+        name, value = pair.split("=", 2)
+        options.key?(name) ? pair : "#{name.tr('-', '_')}=#{value}"
+      end
+
+      # A `--name` flag, as the path of the Boolean argument it stands for. A dashed name
+      # (`--gem-only`) is the argument spelled with underscores (`gem_only`).
+      def flag(name, options)
+        name = name.tr("-", "_") unless options.key?(name) || options.keys.any? { |key| key.start_with?("#{name}.") }
+        path = options.key?(name) ? name : expand(name, options)
+        return path if options.dig(path, :type) == "Boolean"
+
+        raise Runtime::NotFound, "--#{name} is a flag, but this verb has no Boolean argument #{name.inspect}"
+      end
+
+      # The one bare word, as a pair for the verb's first argument the launcher does not mint.
+      def positional(word, spec)
+        first = spec[:arguments].find { |argument| !argument[:minted] }
+        return "#{first[:path]}=#{word}" if first
+
+        if spec[:arguments].any?
+          raise Runtime::NotFound, "#{word.inspect} is not name=value; this verb's only argument is its run key, " \
+                                   "which is minted when omitted (run=<key> names one)"
+        end
+
+        raise Runtime::NotFound, "#{word.inspect} is not name=value, and this verb takes no arguments"
+      end
+
+      # Words the refusal for more than one unnamed argument.
+      def too_many_bare(bare)
+        "only one argument may go unnamed, not #{bare.map(&:inspect).join(', ')}; name the rest as name=value"
+      end
+
+      # 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?
+
+        [name, value]
+      end
+
+      # 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 value to its declared type; only Integer, Float and Boolean convert.
+      def cast(value, type)
+        case type
+        when "Integer" then Integer(value)
+        when "Float"   then Float(value)
+        when "Boolean" then boolean(value)
+        else value
+        end
+      rescue ArgumentError
+        raise Runtime::TypeMismatch, "#{value.inspect} is not #{type} — the chapter declares this field as #{type}"
+      end
+
+      # Reads a Boolean word: `true`, `yes`, `1` or `on` is true; `false`, `no`, `0` or `off` is
+      # false; case does not matter. Anything else is refused, since guessing would turn a typo
+      # (`dry_run=ture`) into a silent false.
+      #
+      # @param value [String] the word
+      # @return [Boolean]
+      # @raise [Runtime::TypeMismatch] if the word is not one of those eight
+      def boolean(value)
+        BOOLEAN_WORDS.fetch(value.to_s.downcase) do
+          raise Runtime::TypeMismatch,
+                "#{value.inspect} is not Boolean — use true, false, yes, no, 1, 0, on or off"
+        end
+      end
+
+      # Appends one element to a list argument, creating the list on first use.
+      #
+      # 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] ||= {} }
+        list   = holder[branches.last] ||= []
+
+        list << { leaf => value }
+        hash
+      end
+
+      # Adds the words of a `list_of` scalar argument to its Array: a comma-separated value is
+      # several elements and a repeated name adds more, each cast to the element type. The
+      # runtime refuses a lone scalar for a list, so the door is where every spelling becomes an
+      # Array.
+      #
+      # @param hash [Hash{Symbol => Object}] the arguments built so far
+      # @param path [Array<String>] the argument's dotted path
+      # @param value [String] the word after `=`
+      # @param type [String] the element type
+      # @return [Hash{Symbol => Object}] `hash`
+      def words(hash, path, value, type)
+        *branches, leaf = path.map(&:to_sym)
+        holder = branches.reduce(hash) { |node, key| node[key] ||= {} }
+        list   = holder[leaf] ||= []
+        list.concat(value.split(",").map { |word| cast(word.strip, type) })
+        hash
+      end
+
+      # 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] ||= {} }
+        target[leaf] = value
+        hash
+      end
+
+      # Words the refusal for an argument the verb does not take, listing what it does.
+      def unknown(path, known)
+        "no argument #{path.inspect} — this verb takes #{known.sort.join(', ')}"
+      end
+    end
+  end
+end

data/lib/hecks/doors/cli_runner.rb

@@ -0,0 +1,297 @@
+require "json"
+require_relative "cli_door"
+require_relative "command_request"
+require_relative "json_door"
+require_relative "launcher_options"
+require_relative "../projector"
+require_relative "../ports/clock"
+
+module Hecks
+  module Doors
+    # Parses and dispatches a command line against a `Projector::CliProjector` projection.
+    # Does no IO: it answers `[text, status]` and leaves printing and exiting to its callers.
+    module CliRunner
+      # The class an adapter raises when the tool it wraps refuses.
+      TOOL_REFUSAL = "Hecks::Adapters::ConsoleCapture::Failure".freeze
+
+      module_function
+
+      # Runs one command line against a booted domain and answers the text to print.
+      # The booted domain's own chapter is projected, or an attached one its first word names.
+      #
+      # @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 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: "hecks run")
+        plan = resolve(runtime, argv, program)
+        return plan[:answer] if plan[:answer]
+
+        dispatch(runtime, plan[:spec], plan[:name], plan[:rest], plan[:program], plan[:asking],
+                 bluebook: plan[:bluebook], launcher: plan[:launcher])
+      end
+
+      # Answers a command line that asks only for usage, from the projection alone.
+      #
+      # Needs a registry and no bound adapter, so a `Runtime::Loader::Described` serves: the
+      # help text, the no-argument usage, a verb's `--help` and an unknown verb's hint all come
+      # out byte-identical to `call`'s.
+      #
+      # @param runtime [#registry] a booted domain, or what `Hecks.describe` answers
+      # @param argv [Array<String>] as for `call`
+      # @param program [String] how the caller was invoked
+      # @return [Array(String, Integer), nil] the text and status, or nil when the line would
+      #   run a verb or question and so needs a booted domain
+      def usage(runtime:, argv:, program: "hecks run")
+        resolve(runtime, argv, program)[:answer]
+      end
+
+      # Parses a command line against the projection: either the answer it gives without
+      # running anything, or the verb it would run.
+      #
+      # @return [Hash] `{answer: [text, status]}`, or `{spec:, name:, rest:, asking:, program:,
+      #   bluebook:, launcher:}` for a verb to dispatch
+      def resolve(runtime, argv, program)
+        bluebook, argv, program = chapter_for(runtime, argv, program)
+        launcher = LauncherOptions.settings(runtime, bluebook.name)
+        options  = LauncherOptions.projection(launcher, program)
+        cli = Projector.call(:cli, bluebook: bluebook, options: options)
+
+        name = argv.first
+        return { answer: [cli[:usage], 0] } if name.nil? || %w[--help -h help].include?(name)
+
+        # `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 { answer: [cli[:usage], 1] } if name.nil?
+
+        # A question answers to its bare name too; `ask` is needed only when a command shares it.
+        asking ||= !cli[:names][:command].key?(name) && cli[:names][:question].key?(name)
+
+        # 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]
+        return { answer: [unknown(cli, name, asking, program), 1] } unless spec
+
+        rest = argv[1..]
+        if rest.include?("--help")
+          help = Projector.call(:cli, bluebook: bluebook,
+                                      options:  options.merge(verb: name, ask: asking))[:usage]
+          return { answer: [help, 0] }
+        end
+
+        { spec: spec, name: name, rest: rest, asking: asking, program: program, bluebook: bluebook,
+          launcher: launcher }
+      end
+
+      # The chapter a command line speaks to: the booted domain's own, or, when the first word
+      # names a chapter its hecksagon attaches or uses as a framework member (`deploy`,
+      # `governance`), that chapter, with the word dropped and added to the program name.
+      def chapter_for(runtime, argv, program)
+        own      = runtime.registry.bluebooks.values.first
+        attached = Array(runtime.registry.hecksagon(own.name)&.member_chapters)
+        target   = attached.find { |name| Naming.snake(name) == argv.first }
+        return [own, argv, program] unless target
+
+        [runtime.registry.bluebook(target), argv[1..], "#{program} #{argv.first}"]
+      end
+
+      # 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]`. With `--wait`, a
+      # question whose report names a gap (`LauncherOptions.gap_reported?`) answers status 1.
+      #
+      # @param bluebook [Bluebook::Chapter] the chapter the verb belongs to
+      # @param launcher [Hash, nil] the chapter's `launcher` world setting; nil when not opted in
+      def dispatch(runtime, spec, name, rest, program, asking, bluebook: nil, launcher: nil)
+        rest, wait = LauncherOptions.take_wait(spec, rest) if launcher
+        args = stamp_time(runtime, spec, CliDoor.arguments(spec, rest))
+
+        return answer_query(runtime, spec, args, wait) if spec[:kind] == :query
+
+        args, minted = LauncherOptions.run_key(runtime, spec, args, launcher)
+        # 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)
+        extra  = refused_answer(handle)
+        extra  = { run: minted }.merge(extra) if minted
+        return settled(runtime, spec, handle, bluebook, launcher, extra) if wait
+        return [JSON.pretty_generate(answered(handle).merge(extra)), 0] if handle.state.nil?
+
+        [JSON.pretty_generate({ id:     handle.id,
+                                state:  JsonDoor.materialize(handle.state),
+                                events: handle.events.map(&:name) }.merge(extra)), 0]
+      rescue Runtime::NotFound, Runtime::TypeMismatch => e
+        # 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 chapter's own sentence, verbatim.
+        [e.message, 1]
+      rescue StandardError => e
+        # So is a wrapped tool's, when a question's adapter refuses to answer. Matched by name: the
+        # adapters belong to the Hecks chapter, which a client's runtime never loads.
+        raise unless e.class.ancestors.map(&:name).include?(TOOL_REFUSAL)
+
+        [e.message, 1]
+      end
+
+      # Runs a question and answers its rows, or its text when an adapter answered in text.
+      #
+      # @param wait [Boolean, nil] whether `--wait` was given: a report naming a gap then fails
+      # @return [Array(String, Integer)] the answer and the status
+      def answer_query(runtime, spec, args, wait)
+        rows = runtime.query(spec[:verb], **args)
+        text = text_answer(spec, rows)
+        [text || JSON.pretty_generate(rows.map { |row| JsonDoor.materialize(row) }),
+         wait && LauncherOptions.gap_reported?(text) ? 1 : 0]
+      end
+
+      # The answer `--wait` gives: the record re-read after every reaction has run, with all its
+      # events, and a status of 1 when its lifecycle ended in a failure state, a refused reaction
+      # blocks the run or a reaction crashed.
+      #
+      # A refusal blocks unless a sibling reaction delivered another command on the same
+      # aggregate (`Runtime::ReactionOutcome`). The settled record is always the text, so a failed
+      # run pipes like a passing one; the reason a human reads is a third element.
+      #
+      # @return [Array(String, Integer)] the JSON and the status, plus (Array(String, Integer,
+      #   String)) why the run failed when it did
+      def settled(runtime, spec, handle, bluebook, launcher, extra)
+        why = reactions_failed(handle)
+        return finish(JSON.pretty_generate(answered(handle).merge(extra)), why) if handle.state.nil?
+
+        aggregate = aggregate_of(bluebook, spec)
+        state     = reread(runtime, bluebook, aggregate, handle) || handle.state
+        fqn       = "#{bluebook.name}::#{aggregate&.hecks_name}"
+        events    = runtime.events.select { |event| event.aggregate == fqn && event.id == handle.id }
+        answer    = { id: handle.id, state: JsonDoor.materialize(state),
+                      events: (events.empty? ? handle.events : events).map(&:name) }.merge(extra)
+        if LauncherOptions.failed?(aggregate, state, launcher)
+          field = aggregate.lifecycle.field
+          why  += ["#{aggregate.hecks_name} ended in the failure state #{state[field.to_sym].to_s.inspect}"]
+        end
+        finish(JSON.pretty_generate(answer), why)
+      end
+
+      # The answer and its status: 0 when nothing failed, else 1 with the reasons joined.
+      def finish(text, reasons)
+        reasons.empty? ? [text, 0] : [text, 1, reasons.join("\n")]
+      end
+
+      # What the reactions of the run the handle reports did wrong: each refusal that blocks it
+      # and each crash, as one sentence apiece.
+      def reactions_failed(handle)
+        blocking = handle.respond_to?(:blocking_reactions) ? handle.blocking_reactions : []
+        crashed  = handle.respond_to?(:reaction_defects) ? handle.reaction_defects : []
+        blocking.map { |row| "reaction #{row[:policy]} was refused (#{row[:trigger]}): #{row[:reason]}" } +
+          crashed.map { |row| "reaction #{row[:policy]} crashed (#{row[:error_class]}): #{row[:reason]}" }
+      end
+
+      # Whether a reaction the domain refused blocks the run the handle reports.
+      def blocked?(handle)
+        handle.respond_to?(:blocking_reactions) && !handle.blocking_reactions.empty?
+      end
+
+      # The aggregate a top-level command belongs to; nil for an entity command or a port.
+      def aggregate_of(bluebook, spec)
+        head = spec[:verb].split("::", 2).last
+        return if head.count(".") != 1
+
+        bluebook.aggregates.find { |aggregate| aggregate.hecks_name == head.split(".").first }
+      end
+
+      # The record as its repository holds it now, or nil when it cannot be read.
+      def reread(runtime, bluebook, aggregate, handle)
+        return unless aggregate && runtime.respond_to?(:registry)
+
+        runtime.registry.repository(bluebook.name, aggregate)&.find(handle.id)&.to_h
+      end
+
+      # The text a query answered by a port gave, when that is the whole answer.
+      #
+      # A query declared `returns Document` (one value object of the single String attribute
+      # `text`) answers one document; printing it raw keeps the document (JSON, Markdown,
+      # sentences) readable and pipeable instead of quoted inside another JSON document. What a
+      # query declares decides it, not how many rows came back: any other query prints JSON,
+      # so a script reading it sees an array whether it held one row or two.
+      #
+      # @param spec [Hash] the question's projected spec
+      # @param rows [Array<Hash>] the query's rows
+      # @return [String, nil] the text, or nil when the query does not return a Document
+      def text_answer(spec, rows)
+        return unless spec[:returns] == "Document" && rows.length == 1 && rows.first.keys == [:text]
+        return unless rows.first[:text].is_a?(String)
+
+        rows.first[:text]
+      end
+
+      # Fills in a `now` argument the caller left out, from the clock port; an explicit one wins.
+      #
+      # 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)
+
+        args.merge(now: { value: Ports::Clock.now(runtime.registry) })
+      end
+
+      # The reactions one dispatch caused that the domain refused, as `refused_reactions:`.
+      #
+      # A policy's trigger that a `given` refuses is not the command's own refusal: the command
+      # has already persisted. The dispatch result carries them (`Result#refused_reactions`);
+      # without this the answer would say nothing of it. A defect (a crash) is shown apart, as
+      # `reaction_defects:`, and fails `--wait`.
+      #
+      # @param handle [Runtime::Dispatcher::Result, Runtime::RemoteDispatcher::Result] the outcome
+      # @return [Hash] `refused_reactions:` each with the `policy`, its `trigger` and the `reason`;
+      #   empty when every reaction was delivered (or a remote host sent no per-step log), plus
+      #   `reaction_defects:` when one crashed
+      def refused_answer(handle)
+        refused = handle.respond_to?(:refused_reactions) ? handle.refused_reactions : []
+        defects = handle.respond_to?(:reaction_defects) ? handle.reaction_defects : []
+        answer  = refused.empty? ? {} : { refused_reactions: refused }
+        defects.empty? ? answer : answer.merge(reaction_defects: defects)
+      end
+
+      # Shapes a port operation's outcome, which has no state: each event with its full payload.
+      #
+      # 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)
+        # 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 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: `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 }
+                   .sort_by { |shared, candidate| [-shared, candidate] }
+                   .map(&:last)
+
+        lines = ["no such #{asking ? 'question' : 'verb'}: #{name}"]
+        lines += ["", "did you mean:", *near.first(5).map { |candidate| "  #{candidate}" }] unless near.empty?
+        lines += ["", "  #{program}#{' ask' if asking}   for the full list"]
+        lines.join("\n")
+      end
+
+      def shared_prefix(one, other)
+        length = [one.length, other.length].min
+        (0...length).find { |index| one[index] != other[index] } || length
+      end
+    end
+  end
+end

data/lib/hecks/{facade → doors}/command_request.rb

@@ -1,43 +1,25 @@
 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:
+  module Doors
+    # 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