hecks 2.7.0 → 2.9.0

data/lib/hecks/facade/handle.rb

@@ -4,18 +4,8 @@ require_relative "../ports/authorization"
 
 module Hecks
   module Facade
-    # One record in hand — the object `Pizza.create_pizza!(...)` and
-    # `Pizza.find(id)` give back.
-    #
-    # One shared class, not one minted per aggregate. Rather than subclassing
-    # per head and defining a reader per field, this wraps a
-    # `Runtime::Instance` state hash, answers readers through
-    # `method_missing` and verbs through per-handle singleton methods, and
-    # closes over the dispatcher and the aggregate's IR — so a boot mints no
-    # classes at all, and two boots in one process each hand out handles bound
-    # to their own dispatcher.
-    #
-    # A non-creating verb is a method returning self, so commands chain :
+    # A record in hand: what `Pizza.create_pizza!(...)` and `Pizza.find(id)`
+    # give back. One shared class per aggregate; verbs are per-handle singleton methods.
     #
     #     Pizza.create_pizza!(...).add_topping!(...).purchase!(...)
     class Handle
@@ -45,22 +35,10 @@ module Hecks
       #   or a referenced record's id); `nil` when the field is unset or not in state
       def [](key) = redacted(key.to_sym)
 
-      # Answers the record's state as a plain Hash with the bare identity under `:id`.
-      #
-      # `id: @id` last, not first — an aggregate is free to declare its own
-      # attribute literally named `id` (BurningManPrep's `Item`, `attribute
-      # :id, ItemId`, is real corpus now: `identified_by :id` reads
-      # that attribute for identity). When it does, `@state[:id]` holds the
-      # full wrapped value object, not the bare identity string — merging
-      # `@state` on top of `{ id: @id }` would let that wrapped VO silently
-      # clobber the correct bare `@id`, so every caller of `to_h` (the JSON
-      # door's own `/api/:coll` listing, in particular) would get an object
-      # where a plain identity string belongs. `@id` merged last always wins,
-      # so `to_h[:id]` is always the true bare identity, regardless of
-      # whether the aggregate also happens to declare a same-named field.
+      # Answers the record's state as a Hash, with `:id` merged in last so it
+      # always wins over a same-named `id` attribute (BurningManPrep::Item).
       #
-      # @return [Hash{Symbol => Object}] a new Hash of every state field by attribute
-      #   name, plus `:id` holding the identity String
+      # @return [Hash{Symbol => Object}] every state field by attribute name, plus `:id`
       def to_h = @state.to_h { |key, _| [key, redacted(key)] }.merge(id: @id)
 
       # Names the aggregate this record belongs to, in the form every dispatch verb and
@@ -90,14 +68,11 @@ module Hecks
         self
       end
 
-      # Equality is (which aggregate, which ID) — two handles to the same record
-      # are the same record, and a Pizza never equals an Account that happens to
-      # share an id. With one shared class for every aggregate,
-      # `other.is_a?(self.class)` cannot tell them apart ; the fqn says it in data.
+      # Equality is (fqn, id): two handles to the same record are equal, and
+      # `other.is_a?(self.class)` can't tell aggregates apart since they share one class.
       #
       # @param other [Object] anything; only another `Handle` can be equal
-      # @return [Boolean] true when `other` is a `Handle` with the same `fqn` and `id`,
-      #   whatever state either one holds
+      # @return [Boolean] true when `other` is a `Handle` with the same `fqn` and `id`
       def ==(other) = other.is_a?(Handle) && other.fqn == fqn && other.id == @id
       alias eql? ==
       def hash = [Handle, fqn, @id].hash
@@ -108,18 +83,13 @@ module Hecks
       end
       alias to_s inspect
 
-      # Answers a field reader: `pizza.name` reads `name` out of state.
-      #
-      # A declared field not yet written arrives here too (nil, the way a
-      # defined reader answers). Verbs are not handled here — see
-      # `define_verb_methods` for why.
+      # Answers a field reader: `pizza.name` reads `name` out of state. A
+      # declared field not yet written arrives here too, as `nil`.
       #
       # @param name [Symbol] the method called, read as an attribute or lifecycle field name
       # @param args [Array<Object>] ignored by a reader; passed on to `super` otherwise
-      # @param kwargs [Hash{Symbol => Object}] ignored by a reader; passed on to `super`
-      #   otherwise
-      # @return [Object, nil] the field's value; `nil` for a declared field with nothing
-      #   written yet
+      # @param kwargs [Hash{Symbol => Object}] ignored by a reader; passed on to `super` otherwise
+      # @return [Object, nil] the field's value; `nil` when nothing is written yet
       # @raise [NoMethodError] if `name` is neither a key in state nor a declared field
       def method_missing(name, *args, **kwargs, &)
         return redacted(name) if @state.key?(name) || reader?(name)
@@ -135,28 +105,9 @@ module Hecks
 
       def repository = @dispatcher.registry.repository(@domain, @ir)
 
-      # One field's value, with any Privacy::Marking-flagged leaf masked
-      # out unless the ambient caller holds a live Governance grant of
-      # the marking's own `readable_by` — the read-side half of the
-      # Privacy framework member (lib/hecks/framework/bluebook/
-      # privacy.bluebook): a marking's presence is what makes a read
-      # redacted, not a separate flag this class carries itself.
-      #
-      # ALWAYS THE STRONG CHECK, never the weak string-only fallback
-      # `CommandRules::Authorization#refuse_role_mismatch` allows an
-      # unidentified caller — a read gate gone wrong is a leak, not a
-      # refused command, so an ambient caller with no `actor_id` (or no
-      # caller at all) is masked here, full stop, rather than waved
-      # through the way a self-asserted `role` string is for a command.
-      #
-      # ONE LEVEL OF NESTING ONLY — `attendee.medications` masks inside
-      # the returned `Runtime::Value` via its own `#with`; a marking two
-      # levels deep is not supported and is left unmasked rather than
-      # silently mishandled, since nothing in this corpus needs it yet.
-      #
-      # @param field [Symbol] the state key being read
-      # @return [Object, nil] `@state[field]`, or a copy with the marked leaf replaced by
-      #   the literal String `"[redacted]"` when the caller is not authorized to see it
+      # Masks any Privacy::Marking leaf the caller isn't granted to read, and
+      # masks an unidentified caller outright (a leak is worse than a refusal
+      # commands allow). Nesting is masked one level deep only.
       def redacted(field)
         raw = @state[field]
         rows = marked_paths.select { |row| row[:attribute_path][:value].to_s.split(".", 2).first == field.to_s }
@@ -177,12 +128,8 @@ module Hecks
         raw
       end
 
-      # Every Privacy::Marking declared for this record's own aggregate — `[]` when the
-      # Privacy framework member is not attached in this boot at all, checked once and
-      # cheaply rather than paying for a query dispatch every read on a domain that never
-      # attached Privacy.
-      #
-      # @return [Array<Hash>] `Privacy::Marking.ForDomain`'s own rows for this `fqn`
+      # Cached per handle so an unattached-Privacy domain never pays for a query
+      # dispatch on every read.
       def marked_paths
         return @marked_paths if defined?(@marked_paths)
         return @marked_paths = [] unless @dispatcher.registry.bluebook("Privacy")
@@ -190,13 +137,8 @@ module Hecks
         @marked_paths = @dispatcher.query("Privacy::Marking.ForDomain", domain: fqn)
       end
 
-      # Whether the ambient caller holds a live Governance grant of `role`, over this
-      # record's own domain — `false` outright for an unidentified caller or a domain
-      # with no authorization provider attached, never the weak fallback a command's own
-      # role check allows (see `redacted`'s own header for why).
-      #
-      # @param role [String] the marking's own `readable_by`
-      # @return [Boolean] true only for an identified caller holding a live grant
+      # False outright for an unidentified caller or an unattached domain, never
+      # the weak fallback a command's own role check allows.
       def authorized_for?(role)
         caller = Runtime::Caller.current
         return false unless caller&.actor_id
@@ -210,20 +152,9 @@ module Hecks
         !@ir.attribute(name).nil? || @ir.lifecycle&.field&.to_sym == name
       end
 
-      # Non-creating verbs are defined, not dispatched through method_missing.
-      #
-      # method_missing only runs once Ruby finds no real method already
-      # answering the name — and every object already answers `freeze` and
-      # `send` (Kernel/Object), among others. A verb whose snake-cased name
-      # collided with one of those — `Account::Freeze` -> `freeze`,
-      # `ExternalTransfer::Send` -> `send` in the banking corpus, both real —
-      # would silently run the Kernel method instead of dispatching: no
-      # error, no refusal, the call just does the wrong thing. Defining a
-      # real singleton method per verb closes that; the `!` suffix (every
-      # command, door and Handle alike) closes it a second, permanent way —
-      # `freeze!`/`send!` name nothing Kernel/Object already answers to,
-      # so this exact class of collision cannot recur no matter what a
-      # future domain names a command.
+      # Real singleton methods, not method_missing: a verb named `freeze` or
+      # `send` (both real, e.g. Account::Freeze, ExternalTransfer::Send) would
+      # otherwise silently hit the Kernel method instead of dispatching.
       def define_verb_methods
         @ir.commands.reject(&:creates?).each do |command|
           define_singleton_method("#{Naming.snake(command.hecks_name)}!") do |**args|
@@ -232,42 +163,24 @@ module Hecks
         end
       end
 
-      # One head addresses the same way as several. `@ir.identified_by` is only
-      # the single-head shorthand — nil the moment an identity is composite
-      # (`SafeDepositBox`'s `branch_code`/`box_number`) — so building the
-      # identity payload from `identity_heads` instead reads every head, one
-      # or many alike, straight out of state that already carries them.
+      # `@ir.identified_by` is only the single-head shorthand (nil for a
+      # composite identity, e.g. SafeDepositBox's branch_code/box_number);
+      # this reads every head through `identity_heads` instead.
       def run(command, **args)
         @state = @dispatcher.dispatch("#{fqn}.#{command.hecks_name}", to: @id, with: args).instance.state
         self
       end
 
-      # **The other half of a cross-reference**. `transfer.source` already reads
-      # the raw value — a plain reader, same as any other attribute, still
-      # needed by a `given`. This is the hydrated hop docs/rails-integration.md
-      # designed and marked "nothing built": `transfer.source_account`
-      # resolves it to the actual Account record, on demand — nothing loads
-      # until called, and this hop never triggers the next one. Plain
-      # chaining composes for free from here : `payment.disputed_by_customer.name`
-      # is two ordinary calls, each individually lazy, which is exactly why
-      # this is a named accessor per reference rather than a `through:`
-      # option — that shape was considered and rejected in the same design
-      # note for hiding how many lookups actually happened behind one call.
+      # Lazy hop: `transfer.source_account` resolves to the actual record only
+      # when called; nothing loads until then, so chains like
+      # `payment.disputed_by_customer.name` stay lazy at every step.
+      #
+      # Defined before verb methods so a same-named verb wins the name on the
+      # rare collision; `initialize` calls this first for that reason.
       #
-      # Defined before verb methods, not after — on the vanishing chance a
-      # reference's own accessor name collided with a command's, the verb
-      # should win; `initialize` calls this first so `define_verb_methods`
-      # defines second and last.
-      # No derivation left (ADR 0025, "References"): `reference_to`
-      # itself mints the bare attribute name now — `:account`, never
-      # `:account_id` — so the accessor is spelled exactly like the
-      # attribute it reads, with no `_id`-strip or `as:`-suffix rule to
-      # apply first. `piece.account` (a method, defined here) and
-      # `piece[:account]` (`Handle#[]`, bracket access reading the raw
-      # id straight off `@instance`) never collide despite sharing a
-      # name — Ruby dispatches the two completely differently — so no
-      # renamed accessor (a "studio_studio"-style double suffix) is needed
-      # to keep them apart.
+      # The accessor is named like the attribute itself, never `<name>_id`
+      # (ADR 0025) — `piece.account` and `piece[:account]` (bracket access,
+      # the raw id) never collide despite sharing a name.
       def define_reference_accessors
         @ir.attributes.select(&:reference?).each do |attribute|
           target = attribute.type.resolve

data/lib/hecks/facade/json_door.rb

@@ -7,73 +7,23 @@ require_relative "../runtime/value"
 
 module Hecks
   module Facade
-    # **The JSON door** — where Facade meets body-in/body-out callers.
-    #
-    # `Handle`/`Surface` are Ruby sugar over the dispatcher for a Ruby caller
-    # holding real objects — a symbol verb name, a `**kwargs` payload, a
-    # `Handle` back in hand. A REST-ish JSON API is a caller holding strings
-    # instead: a URL segment naming a collection, a URL segment naming a
-    # record or a verb, a parsed request body whose every key arrived as a
-    # String because that is all JSON ever gives. Every app that wants to put
-    # a JSON API in front of a booted domain has to do that translation —
-    # name to door module, string to symbol, nested `Runtime::Value` back to
-    # plain data. This is that translation written once, generic, reading the
-    # same IR the rest of the facade already reads rather than each app
-    # re-deriving "how do I find an aggregate by name" against its own routes.
-    #
-    # ## No HTTP lives here
-    #
-    # Same discipline `Router` and `Surface` already
-    # hold: this module never sees a request object, never picks a status
-    # code, never calls `halt`. Every method here takes plain Ruby values in
-    # — a raw JSON String is the one exception, see `.parse` below, every
-    # other input is already-parsed data — and returns plain Ruby values
-    # out, or raises. Turning a raw request body into that input, and
-    # turning a raised exception into an HTTP status, both stay the calling
-    # app's job, exactly the way they already are for `Router#dispatch`.
-    #
-    # ## One refusal class for every miss
-    #
-    # Every "that doesn't exist" case raises `Runtime::NotFound` — the same
-    # class every time, not a new one per caller. `Runtime::NotFound` already
-    # sits in `Runtime::DOMAIN_REFUSALS` (runtime/errors.rb) — the family a
-    # booted app already has, or trivially can have, one generic `error`
-    # handler for, mapping the whole family to a status code without a
-    # special case per refusal. A bespoke `JsonDoor::CollectionNotFound` (or
-    # three of those, one per flavor of "not found") would just force every
-    # app that adopts this door to widen its rescue clause to match it — the
-    # opposite of what a shared refusal family is for. So "no such
-    # aggregate", "no creating command", "no such command", and "no record
-    # with that id" all raise the one class, distinguished only by message.
+    # The JSON door: translates URL segments and parsed JSON bodies to and from the facade.
+    # No HTTP lives here; every miss raises `Runtime::NotFound`, distinguished by message.
     module JsonDoor
       module_function
 
       # Resolves a domain name and an aggregate name, as two URL segments carry them, to
       # that aggregate's door.
       #
-      # "Banking", "Customer" -> the `Banking::Customer` door module `.find` /
-      # `.create_...!` / etc already answer for — the same module
-      # `Facade::Handle`'s own reference accessors reach with
-      # `Object.const_get` (see handle.rb's `define_reference_accessors`).
+      # The name is checked against the current boot's IR before Ruby's constant table, so
+      # a stale same-named constant from an earlier boot is never returned.
       #
-      # Checked against the current boot's IR first, not against Ruby's
-      # constant table directly — a name that names nothing in this
-      # registry should refuse before ever asking Ruby whether some
-      # same-named constant happens to exist (possibly a stale one, left
-      # over from an earlier boot in this same process — the exact hazard
-      # `AggregateDoor#port`'s own comment describes at length). Only once
-      # the IR confirms the aggregate is real does this read the constant
-      # the current boot's `Surface.install` actually minted for it.
-      #
-      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
-      #   dispatcher whose registry decides whether the aggregate exists
+      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted dispatcher
       # @param domain [String, Symbol] the chapter name, such as `"Banking"`
       # @param name [String, Symbol] the aggregate's declared name, such as `"Customer"`
       # @return [Module] the aggregate door installed at `domain::name`
-      # @raise [Runtime::NotFound] if the registry holds no such chapter, or the chapter
-      #   declares no aggregate of that name
-      # @raise [NameError] if the IR has the aggregate but no facade constant is
-      #   installed for it, as after a boot with `install_facade: false`
+      # @raise [Runtime::NotFound] if the chapter or its aggregate is not declared
+      # @raise [NameError] if the aggregate has no facade constant (`install_facade: false`)
       def aggregate(dispatcher, domain, name)
         ir = dispatcher.registry.bluebook(domain)&.aggregate(name)
         raise Runtime::NotFound, "#{domain} declares no aggregate named #{name.inspect}" unless ir
@@ -81,21 +31,11 @@ module Hecks
         Object.const_get("#{domain}::#{ir.hecks_name}")
       end
 
-      # Names the door method that creates a record of this aggregate.
-      #
-      # The one command a POST to a bare collection URL means — "make one of
-      # these". A creating command is one that declares no `references`
-      # (`Command#creates?`), and the first one the aggregate declares is the
-      # one named here; this just names it the same
-      # snake_case-plus-bang a Ruby caller would already ask the door for
-      # (`Naming.snake`, the identical call `AggregateDoor` itself makes
-      # when it defines that singleton method in the first place — `!`
-      # because every command carries it, door and Handle alike).
+      # Names the door method that creates a record of this aggregate: the first command
+      # it declares that `creates?`, spelled as a Ruby caller would (`"create_pizza!"`).
       #
-      # @param klass [Module] an aggregate door, as `aggregate` returns; anything
-      #   answering `ir` with a `Bluebook::Aggregate` works
-      # @return [String] the method name to `public_send` to the door, such as
-      #   `"create_pizza!"`
+      # @param klass [Module] an aggregate door, as `aggregate` returns
+      # @return [String] the method name to `public_send` to the door
       # @raise [Runtime::NotFound] if the aggregate declares no creating command
       def creating_command(klass)
         creating = klass.ir.commands.find(&:creates?)
@@ -107,28 +47,14 @@ module Hecks
       # Confirms that a command name arriving as text is one a `Handle` of this aggregate
       # answers, before a caller `public_send`s it.
       #
-      # A URL segment or a JSON body's "command" field, checked against what
-      # a `Handle` can actually dispatch — not `klass.commands`, which is
-      # `AggregateDoor`'s own door-level list and includes the one creating
-      # command too (`aggregate_door.rb`'s `commands` singleton method maps
-      # every `ir.commands`, full stop). A `Handle` only ever defines
-      # singleton methods for the non-creating ones
-      # (`Handle#define_verb_methods`, `@ir.commands.reject(&:creates?)`) —
-      # the creating command lives on the aggregate class itself, dispatched
-      # through `.creating_command` above, not through a `Handle` in hand.
-      # Accepting a creating-command name here would let it past this gate
-      # clean, only to blow up as a raw `NoMethodError` the moment a caller
-      # tries `handle.public_send(name, **args)`, instead of the 404 this
-      # method promises. Filtering `reject(&:creates?)` here, the same filter
-      # `Handle` itself applies, is what keeps "accepted here" and
-      # "dispatchable there" the same set.
+      # A `Handle` defines only the non-creating commands, so the creating command is
+      # rejected here rather than failing later as a raw `NoMethodError`.
       #
       # @param klass [Module] an aggregate door, as `aggregate` returns
       # @param name [String, Symbol] the wanted method name with its bang, such as
       #   `"add_topping!"`
       # @return [String] `name` as a String, unchanged, when a `Handle` answers it
-      # @raise [Runtime::NotFound] if no non-creating command has that method name,
-      #   including when `name` is the creating command's or lacks the `!`
+      # @raise [Runtime::NotFound] if no non-creating command has that method name
       def validate_command!(klass, name)
         wanted = name.to_s
         dispatchable = klass.ir.commands.reject(&:creates?).map { |command| "#{Naming.snake(command.hecks_name)}!" }
@@ -137,14 +63,7 @@ module Hecks
         raise Runtime::NotFound, "#{klass.ir.hecks_name} declares no command named #{wanted.inspect}"
       end
 
-      # Fetches one record by id, refusing a miss instead of answering nil.
-      #
-      # `klass.find` already answers nil-on-miss — the right shape for a
-      # Ruby caller that means to check for itself. A JSON caller asking for
-      # one record by id off a URL means to have it, or answer 404 — this is
-      # that stricter wrapper, raising the same `Runtime::NotFound` the rest
-      # of this door raises rather than handing back nil for the caller to
-      # remember to check.
+      # Fetches one record by id, raising instead of answering nil on a miss.
       #
       # @param klass [Module] an aggregate door, as `aggregate` returns
       # @param id [String] the record's identity, as the URL carried it
@@ -156,11 +75,6 @@ module Hecks
 
       # Converts every Hash key to a Symbol, at every depth of a parsed JSON body.
       #
-      # JSON only ever hands back String keys. A command's args, and every
-      # nested value-object literal inside them, need symbol keys before
-      # `Handle`/`Dispatcher` will accept them at all — this is that
-      # recursive conversion, blind to how deep a body nests.
-      #
       # @param value [Hash, Array, Object] parsed JSON: a Hash or Array is walked, any
       #   other value is a leaf
       # @return [Hash{Symbol => Object}, Array, Object] a new structure of the same shape
@@ -174,72 +88,43 @@ module Hecks
       end
 
       # Unwraps a record, a query row, or any value holding `Runtime::Value`s into plain
-      # Hashes, Arrays and scalars.
+      # Hashes, Arrays and scalars a JSON encoder can walk.
       #
-      # The other direction: a `Handle`, or a query row's plain state hash,
-      # carrying a `Runtime::Value` at every level a value object sits at —
-      # down to plain Ruby a JSON encoder can walk without knowing what a
-      # `Runtime::Value` is.
-      #
-      # `Runtime::Value.materialize` (runtime/value.rb) already does the
-      # actual recursion — its `Hash` branch calls itself on every value,
-      # its `Value` branch unwraps through `#to_h`, which itself calls
-      # `materialize` on every field, so a value object three levels deep
-      # unwraps three levels deep for free. This is not a second unwrapper
-      # sitting next to it: `materialize` covers `Hash`/`Array`/`Value`
-      # already, and a `Handle` is none of those three, so the one thing
-      # this adds is `#to_h`'ing a `Handle` first so `materialize`'s own
-      # `Hash` case can take it from there.
+      # Delegates to `Runtime::Value.materialize`; the only addition is `#to_h` on a
+      # `Handle`, which `materialize` does not recognize.
       #
       # @param value [Facade::Handle, Runtime::Value, Hash, Array, Object] what to unwrap;
       #   a `Handle` is read through its `to_h`, so its `:id` comes along
       # @return [Hash, Array, Object] the same data with every `Runtime::Value` replaced
-      #   by a Hash of its fields; a value that is none of the listed types is returned
-      #   as it came
+      #   by a Hash of its fields; any other value is returned as it came
       def materialize(value)
         value = value.to_h if value.is_a?(Handle)
         Runtime::Value.materialize(value)
       end
 
       # Turns a command's JSON body, raw or already parsed, into the `to:`/`with:`
-      # envelope a dispatcher takes.
-      #
-      # Parsed JSON and raw JSON text cross the same receiver/payload boundary
-      # as CLI and forms. The result is ready to splat into Dispatcher#dispatch
-      # and contains no loose routing fields.
-      #
-      # @param body [String, Hash] raw JSON text, or the Hash it parses to, with String
-      #   or Symbol keys
-      # @param receiver [Symbol, nil] the kind of receiver the command takes: `:aggregate`,
-      #   `:entity`, or `nil` for none (see `CommandRequest.normalize`)
-      # @param legacy_receiver [Symbol, String, Hash{Symbol => Symbol, String}, nil] the
-      #   flat key, or pair of keys, a body without `to` may name its receiver under;
-      #   `nil` accepts none
-      # @return [Hash{Symbol => Object}] `{ with: facts }`, plus `to:` whenever `receiver`
-      #   is not `nil`
+      # envelope a dispatcher takes. The result splats into `Dispatcher#dispatch`.
+      #
+      # @param body [String, Hash] raw JSON text, or the Hash it parses to
+      # @param receiver [Symbol, nil] `:aggregate`, `:entity`, or `nil` for none
+      #   (see `CommandRequest.normalize`)
+      # @param legacy_receiver [Symbol, String, Hash{Symbol => Symbol, String}, nil] the flat key,
+      #   or pair of keys, a body without `to` may name its receiver under; `nil` accepts none
+      # @return [Hash{Symbol => Object}] `{ with: facts }`, plus `to:` unless `receiver` is `nil`
       # @raise [JSON::ParserError] if `body` is a String that is not valid JSON
-      # @raise [Runtime::TypeMismatch] if the body is not a JSON object, or its routing is
-      #   missing, malformed, or mixed with loose keys beside an explicit `with:`
+      # @raise [Runtime::TypeMismatch] if the body is not a JSON object or its routing is malformed
       # @raise [ArgumentError] if `receiver` is not `nil`, `:aggregate` or `:entity`
       def command_request(body, receiver:, legacy_receiver: nil)
         input = body.is_a?(String) ? parse(body) : body
         CommandRequest.normalize(input, receiver: receiver, legacy_receiver: legacy_receiver)
       end
 
-      # Parses a raw request body, leaving keys as Strings.
-      #
-      # The one place a raw JSON string is legitimate input for this door —
-      # a POST body, still text at the point a generic, HTTP-blind layer can
-      # see it. `JSON::ParserError` already names "this wasn't JSON" exactly
-      # right ; wrapping it in a bespoke `JsonDoor`-specific class would
-      # only be a second name for the same fact, so it propagates exactly as
-      # `JSON.parse` raises it — a calling app catches it the same standard
-      # way it would catch any other malformed-input error, no new class to
-      # learn.
+      # Parses a raw request body, leaving keys as Strings. `JSON::ParserError` propagates
+      # unwrapped.
       #
       # @param raw_json [String] JSON text, such as a POST body
       # @return [Hash{String => Object}, Array, String, Numeric, Boolean, nil] whatever
-      #   the text encodes; a JSON object becomes a Hash with String keys
+      #   the text encodes
       # @raise [JSON::ParserError] if the text is not valid JSON
       def parse(raw_json) = JSON.parse(raw_json)
     end