hecks 1.3.0 → 1.4.0

data/lib/hecks/facade/command_request.rb

@@ -16,6 +16,29 @@ module Hecks
     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.
+      #
+      # @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
+      # @raise [ArgumentError] if `receiver` is not `nil`, `:aggregate` or `:entity`
       def normalize(input, receiver:, legacy_receiver: nil)
         request = symbolize(input)
         raise Runtime::TypeMismatch, "a command request must be a hash" unless request.is_a?(Hash)

data/lib/hecks/facade/handle.rb

@@ -2,22 +2,29 @@ require_relative "../naming"
 
 module Hecks
   module Facade
-    # ONE record in hand — the object `Pizza.create_pizza(...)` and
+    # One record in hand — the object `Pizza.create_pizza!(...)` and
     # `Pizza.find(id)` give back.
     #
-    # ONE SHARED CLASS, not one minted per aggregate. The old door subclassed
-    # `Hecks::Aggregate` per head and defined a reader per field ; this
-    # wraps the same `Runtime::Instance` state hash and answers readers and
-    # verbs through `method_missing`, closing 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.
+    # 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 :
     #
-    #     Pizza.create_pizza(...).add_topping(...).purchase(...)
+    #     Pizza.create_pizza!(...).add_topping!(...).purchase!(...)
     class Handle
       attr_reader :id
 
+      # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
+      #   dispatcher this record's verbs, `events` and `reload` go through
+      # @param domain [String] the owning chapter's name, the first half of `fqn`
+      # @param aggregate [Bluebook::Aggregate] the IR of the aggregate this record is one of
+      # @param instance [Runtime::Instance] the stored record; its `id` and `state` are
+      #   read once here and the instance itself is not retained
       def initialize(dispatcher:, domain:, aggregate:, instance:)
         @dispatcher = dispatcher
         @domain     = domain
@@ -28,37 +35,67 @@ module Hecks
         define_verb_methods
       end
 
+      # Reads one field's raw stored value, without hydrating a reference the way the
+      # reference accessor of the same name does.
+      #
+      # @param key [Symbol, String] the attribute name
+      # @return [Object, nil] the value held in state (a scalar, a value object, a list,
+      #   or a referenced record's id); `nil` when the field is unset or not in state
       def [](key) = @state[key.to_sym]
 
-      # `id: @id` LAST, not first — an aggregate is free to declare its own
+      # 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
+      # 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 }` let that wrapped VO silently
+      # `@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) got an object where
-      # a plain identity string belonged. `@id` merged LAST always wins,
+      # 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.
+      #
+      # @return [Hash{Symbol => Object}] a new Hash of every state field by attribute
+      #   name, plus `:id` holding the identity String
       def to_h = @state.merge(id: @id)
 
+      # Names the aggregate this record belongs to, in the form every dispatch verb and
+      # event is addressed by.
+      #
+      # @return [String] the fully qualified aggregate name, such as `"Pizzas::Pizza"`
       def fqn = "#{@domain}::#{@ir.hecks_name}"
 
+      # Lists the events this one record has emitted, filtered out of the dispatcher's
+      # whole event log on each call.
+      #
+      # @return [Array<Runtime::Event>] this record's events in the order the log holds
+      #   them; `[]` when it has emitted none
       def events
         @dispatcher.events.select { |event| event.aggregate == fqn && event.id == @id }
       end
 
+      # Refreshes this handle's state from the repository, picking up writes made through
+      # another handle or door. Keeps the current state when the record is not found.
+      #
+      # @return [Facade::Handle] this handle, so the call chains
+      # @raise [Runtime::WiringError] if the aggregate's persistence bind cannot be
+      #   resolved into a repository
       def reload
         stored = repository.find(@id)
         @state = stored.state if stored
         self
       end
 
-      # Equality is (WHICH AGGREGATE, WHICH ID) — two handles to the same record
+      # 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. The old door said this with `other.is_a?(self.class)`,
-      # leaning on one class per aggregate ; the fqn says it in data.
+      # 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.
+      #
+      # @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
       def ==(other) = other.is_a?(Handle) && other.fqn == fqn && other.id == @id
       alias eql? ==
       def hash = [Handle, fqn, @id].hash
@@ -69,9 +106,19 @@ 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 answered). Verbs are NOT handled here — see
+      # defined reader answers). Verbs are not handled here — see
       # `define_verb_methods` for why.
+      #
+      # @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
+      # @raise [NoMethodError] if `name` is neither a key in state nor a declared field
       def method_missing(name, *args, **kwargs, &)
         return @state[name] if @state.key?(name) || reader?(name)
 
@@ -90,16 +137,16 @@ module Hecks
         !@ir.attribute(name).nil? || @ir.lifecycle&.field&.to_sym == name
       end
 
-      # NON-CREATING VERBS ARE DEFINED, NOT DISPATCHED THROUGH method_missing.
+      # Non-creating verbs are defined, not dispatched through method_missing.
       #
-      # method_missing only runs once Ruby finds no REAL method already
+      # 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 —
-      # used to silently run the Kernel method instead of dispatching: no
-      # error, no refusal, the call just did the wrong thing. Defining a
-      # real singleton method per verb closed that; the `!` suffix (every
+      # 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
@@ -112,7 +159,7 @@ module Hecks
         end
       end
 
-      # ONE HEAD ADDRESSES THE SAME WAY AS SEVERAL. `@ir.identified_by` is only
+      # 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
@@ -122,7 +169,7 @@ module Hecks
         self
       end
 
-      # THE OTHER HALF OF A CROSS-REFERENCE. `transfer.source` already reads
+      # **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`
@@ -134,25 +181,25 @@ module Hecks
       # option — that shape was considered and rejected in the same design
       # note for hiding how many lookups actually happened behind one call.
       #
-      # Defined BEFORE verb methods, not after — on the vanishing chance a
+      # 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`
+      # 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
+      # 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 — which is
-      # what makes the OLD "studio_studio" double-suffix workaround
-      # (this method used to force a DIFFERENT name specifically to dodge
-      # that non-collision) unnecessary rather than merely simplified.
+      # name — Ruby dispatches the two completely differently — so no
+      # renamed accessor (a "studio_studio"-style double suffix) is needed
+      # to keep them apart.
       def define_reference_accessors
         @ir.attributes.select(&:reference?).each do |attribute|
           target = attribute.type.resolve
-          next unless target # cross-domain, or otherwise unresolvable — no accessor rather than a guess
+          # Cross-domain, or otherwise unresolvable — no accessor rather than a guess.
+          next unless target
 
           domain     = @domain
           field      = attribute.name

data/lib/hecks/facade/json_door.rb

@@ -7,22 +7,23 @@ require_relative "../runtime/value"
 
 module Hecks
   module Facade
-    # THE JSON DOOR — WHERE Facade MEETS BODY-IN/BODY-OUT CALLERS.
+    # **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
+    # `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 class, string to symbol, nested `Runtime::Value` back to plain
-    # data — and one sibling app had already hand-written it once, bespoke,
-    # against its own routes, before this existed. This is that translation
-    # pulled out, generic, reading the SAME IR the rest of the facade already
-    # reads rather than re-deriving "how do I find an aggregate by name".
+    # 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
+    # ## 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
@@ -31,10 +32,12 @@ module Hecks
     # turning a raised exception into an HTTP status, both stay the calling
     # app's job, exactly the way they already are for `Router#dispatch`.
     #
-    # EVERY "THAT DOESN'T EXIST" CASE RAISES `Runtime::NotFound` — THE SAME
-    # CLASS EVERY TIME, NOT A NEW ONE PER CALLER. `Runtime::NotFound` already
+    # ## 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`
+    # 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
@@ -45,12 +48,15 @@ module Hecks
     module JsonDoor
       module_function
 
-      # "Banking", "Customer" -> the `Banking::Customer` class `.find` /
-      # `.create_...` / etc already answer for — the same class
+      # 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`).
       #
-      # Checked against the CURRENT boot's IR first, not against Ruby's
+      # 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
@@ -58,6 +64,16 @@ module Hecks
       # `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 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`
       def aggregate(dispatcher, domain, name)
         ir = dispatcher.registry.bluebook(domain)&.aggregate(name)
         raise Runtime::NotFound, "#{domain} declares no aggregate named #{name.inspect}" unless ir
@@ -65,14 +81,22 @@ 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". `AggregateDoor` already enforces exactly one creating
-      # command per aggregate (`Command#creates?`, true exactly when the
-      # command declares no `references`); this just names it the same
+      # 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 does now, door and Handle alike).
+      # because every command carries it, door and Handle alike).
+      #
+      # @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!"`
+      # @raise [Runtime::NotFound] if the aggregate declares no creating command
       def creating_command(klass)
         creating = klass.ir.commands.find(&:creates?)
         raise Runtime::NotFound, "#{klass.ir.hecks_name} declares no creating command" unless creating
@@ -80,21 +104,31 @@ module Hecks
         "#{Naming.snake(creating.hecks_name)}!"
       end
 
+      # 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
+      # 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
+      # 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 let it past this gate clean,
-      # only to blow up as a raw `NoMethodError` the moment a caller tried
-      # `handle.public_send(name, **args)`, instead of the 404 this method
-      # promises. Filtering `reject(&:creates?)` here, the same filter
+      # 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.
+      #
+      # @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 `!`
       def validate_command!(klass, name)
         wanted = name.to_s
         dispatchable = klass.ir.commands.reject(&:creates?).map { |command| "#{Naming.snake(command.hecks_name)}!" }
@@ -103,20 +137,34 @@ 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
+      # 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.
+      #
+      # @param klass [Module] an aggregate door, as `aggregate` returns
+      # @param id [String] the record's identity, as the URL carried it
+      # @return [Facade::Handle] the record in hand
+      # @raise [Runtime::NotFound] if the repository holds no record with that id
       def find!(klass, id)
         klass.find(id) or raise Runtime::NotFound, "no #{klass.ir.hecks_name} found for id #{id.inspect}"
       end
 
+      # 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
+      #   with Symbol keys; a leaf is returned as it came
       def deep_symbolize(value)
         case value
         when Hash  then value.to_h { |k, v| [k.to_sym, deep_symbolize(v)] }
@@ -125,6 +173,9 @@ module Hecks
         end
       end
 
+      # Unwraps a record, a query row, or any value holding `Runtime::Value`s into plain
+      # Hashes, Arrays and scalars.
+      #
       # 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
@@ -139,19 +190,44 @@ module Hecks
       # 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.
+      #
+      # @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
       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`
+      # @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 [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
@@ -160,6 +236,11 @@ module Hecks
       # `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.
+      #
+      # @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
+      # @raise [JSON::ParserError] if the text is not valid JSON
       def parse(raw_json) = JSON.parse(raw_json)
     end
   end

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

@@ -13,16 +13,31 @@ module Hecks
       # `persisted_by`-style binding collector a `.hecksagon` lands on, and
       # the aggregate-scoped `port` a `.hecksagon` lands on beside it.
       module AggregateDoor
+        # Builds the anonymous module that is one aggregate's door: a `name!` method per
+        # creating command, a bare method per query, `find`/`all`/`count`/`events`,
+        # `project`/`docs`/`narrate`, and the `.hecksagon` binding hooks.
+        #
+        # Warns once for each attribute whose name is in `RESERVED`.
+        #
         # One method building one `door` module's ~20 singleton methods
         # looks like it splits along each `define_singleton_method` call,
         # but three of those blocks (`:port`, `:method_missing`,
         # `:const_missing`) are a single cross-referencing essay on the
         # stale-facade-across-boots hazard — each one's comment explicitly
-        # points at "below"/"above" as part of the SAME method. Splitting
+        # points at "below"/"above" as part of the same method. Splitting
         # into helper methods wouldn't break anything at runtime (no
         # shared mutable state beyond the closed-over args, which just
         # become parameters), but it would sever that narrative across
         # method boundaries for no functional gain.
+        #
+        # @param dispatcher [Runtime::Dispatcher, Runtime::RemoteDispatcher] the booted
+        #   dispatcher the door's methods dispatch, query and read repositories through
+        # @param domain [String] the owning chapter's name, the first half of the
+        #   aggregate's FQN (`"Pizzas"` in `"Pizzas::Pizza"`)
+        # @param aggregate [Bluebook::Aggregate] the aggregate to build a door for
+        # @return [Module] a fresh, unnamed module carrying the door's singleton methods
+        # @raise [Bluebook::DSL::Malformed] never while building; the returned door's
+        #   `port` raises it when called with no boot in progress
         # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
         def aggregate_module(dispatcher, domain, aggregate)
           fqn  = "#{domain}::#{aggregate.hecks_name}"
@@ -34,13 +49,13 @@ module Hecks
             warn "[hecks] #{aggregate.hecks_name}##{attribute.name} shadows a built-in — no reader defined"
           end
 
-          # A creating verb is a MODULE method returning the new record in hand ;
+          # A creating verb is a module method returning the new record in hand ;
           # a verb that reaches an existing record lives on the Handle. `!` —
-          # a command DOES something (mutates, may refuse), Ruby's own
-          # convention for that ; `Naming.snake` alone used to leave a
+          # a command does something (mutates, may refuse), Ruby's own
+          # convention for that ; `Naming.snake` alone would leave a
           # creating command's bare name claiming the exact spelling a
-          # QUERY of the SAME business name also wants (`Account`'s own
-          # "Open" — the creating command AND a query listing open
+          # query of the same business name also wants (`Account`'s own
+          # "Open" — the creating command and a query listing open
           # accounts, a real same-aggregate collision this corpus already
           # has) — the suffix is what makes both nameable at all, not
           # merely a style choice.
@@ -51,7 +66,7 @@ module Hecks
             end
           end
 
-          # A query is a MODULE method too — same level as a creating
+          # A query is a module method too — same level as a creating
           # command, since neither needs an existing record in hand — but
           # bare: a query reads and returns, nothing to warn a caller
           # about the way `!` does for a command. Answers the raw row
@@ -66,7 +81,7 @@ module Hecks
           door.define_singleton_method(:fqn)        { fqn }
           door.define_singleton_method(:ir)         { aggregate }
 
-          # THE SAME VERB THE CHAPTER ANSWERS, one level down. Every
+          # The same verb the chapter answers, one level down. Every
           # construct emits its own IR (Hecks::IR), so an aggregate
           # is a legitimate thing to project — `Pizzas::Order.project(
           # Projections::IR)` is this aggregate's IR, not the chapter's.
@@ -74,8 +89,8 @@ module Hecks
           # A chapter-scoped target refuses here rather than inventing an
           # answer: `Projector.admits!` is what tells `Projections::IR`
           # (`from: :any`) apart from `Projections::Shape`
-          # (`from: :chapter`), which used to return a confidently empty
-          # `{"aggregates" => []}` for an aggregate.
+          # (`from: :chapter`), which would otherwise answer a confidently
+          # empty `{"aggregates" => []}` for an aggregate.
           door.define_singleton_method(:project) do |target, out: nil, **options|
             key      = Projector.key_for(target)
             artifact = Projector.call(key, bluebook: aggregate, options: options)
@@ -88,7 +103,7 @@ module Hecks
             aggregate.commands.map { |c| "#{Naming.snake(c.hecks_name)}!" }.sort
           end
           door.define_singleton_method(:queries) { aggregate.queries.map { |q| Naming.snake(q.hecks_name) }.sort }
-          # ONE AGGREGATE'S USAGE DOCUMENT — the same projection the chapter
+          # **One aggregate's usage document** — the same projection the chapter
           # answers with, narrowed to this head. `commands` above already
           # answers "what can I call"; this answers "and what does each one
           # want, refuse, and guarantee", which is the rest of the question.
@@ -96,7 +111,7 @@ module Hecks
             Projector.call(:docs, bluebook: dispatcher.registry.bluebook(domain),
                                   options:  options.merge(aggregate: aggregate.hecks_name))
           end
-          # ONE AGGREGATE, READ BACK IN ENGLISH — the same narrowing `:docs`
+          # **One aggregate, read back in english** — the same narrowing `:docs`
           # takes, aimed at `:narrate` instead.
           door.define_singleton_method(:narrate) do |**options|
             Projector.call(:narrate, bluebook: dispatcher.registry.bluebook(domain),
@@ -116,18 +131,18 @@ module Hecks
             end
           end
 
-          # THE SAME REASON `method_missing` BELOW EXISTS AT ALL — a facade
-          # left over from a PREVIOUS boot in this process shadows the fresh
+          # The same reason `method_missing` below exists at all — a facade
+          # left over from a previous boot in this process shadows the fresh
           # `BindingProxy` a `.hecksagon` would otherwise reach through
           # `ConstShim`/`const_missing`, so `Pizzas::Pizza.port(...)` lands
-          # HERE instead once any boot has run before.
+          # here instead once any boot has run before.
           #
-          # RE-RESOLVED, NOT THE CLOSED-OVER `aggregate` — this door can be a
-          # STALE one, built by a boot from earlier in this same process,
+          # Re-resolved, not the closed-over `aggregate` — this door can be a
+          # stale one, built by a boot from earlier in this same process,
           # sitting on the `Pizzas`/`Pizza` constants only because nothing
-          # has re-installed them since. Attaching to this door's OWN
+          # has re-installed them since. Attaching to this door's own
           # `aggregate` would attach the port to a discarded aggregate from
-          # that old boot, invisible to the CURRENT one actually being
+          # that old boot, invisible to the current one actually being
           # loaded — silently, the exact way `method_missing` below already
           # has to avoid it for a plain bind, via `HecksagonBuilder.collector`
           # rather than anything this door closes over. `Hecks.current_registry`
@@ -166,18 +181,18 @@ module Hecks
             !Bluebook::DSL::HecksagonBuilder.collector.nil? || super(name, include_private)
           end
 
-          # THE SAME STALE-FACADE HAZARD `method_missing`/`port` ABOVE ALREADY
-          # DOCUMENT, one door lower — `Surface.install` installs an aggregate's
-          # OWN name as a bare TOP-LEVEL constant too (`Namespace.install(Object,
+          # The same stale-facade hazard `method_missing`/`port` above already
+          # document, one door lower — `Surface.install` installs an aggregate's
+          # own name as a bare top-level constant too (`Namespace.install(Object,
           # aggregate.hecks_name, ...)`, surface.rb's own `install`), not only
-          # nested under its chapter. So once ANY domain has booted once in this
-          # process, `Account::Debit` written while declaring some OTHER
-          # bluebook — same domain or a different one — reaches THIS door's
+          # nested under its chapter. So once any domain has booted once in this
+          # process, `Account::Debit` written while declaring some other
+          # bluebook — same domain or a different one — reaches this door's
           # const_missing directly, never `Object.const_missing`/`ConstShim::
           # Hook` at all: real modules resolve without ever calling that.
           #
-          # `aggregate.hecks_name`, NOT the qualified `fqn` — a scoped
-          # reference has to read the SAME either way, whether or not a stale
+          # `aggregate.hecks_name`, not the qualified `fqn` — a scoped
+          # reference has to read the same either way, whether or not a stale
           # door happens to be sitting on this process from an earlier boot;
           # qualifying it here would make `Account::Debit`'s own meaning
           # depend on incidental process history, which is the exact