hecks 1.3.0 → 1.5.0

data/lib/hecks/facade/handle.rb

@@ -1,23 +1,32 @@
 require_relative "../naming"
+require_relative "../runtime/caller"
+require_relative "../ports/authorization"
 
 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 +37,67 @@ module Hecks
         define_verb_methods
       end
 
-      def [](key) = @state[key.to_sym]
+      # 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) = redacted(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.
-      def to_h = @state.merge(id: @id)
+      #
+      # @return [Hash{Symbol => Object}] a new Hash of every state field by attribute
+      #   name, plus `:id` holding the identity String
+      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
+      # 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,11 +108,21 @@ 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)
+        return redacted(name) if @state.key?(name) || reader?(name)
 
         super
       end
@@ -86,20 +135,91 @@ 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
+      def redacted(field)
+        raw = @state[field]
+        rows = marked_paths.select { |row| row[:attribute_path][:value].to_s.split(".", 2).first == field.to_s }
+        return raw if rows.empty?
+
+        rows.each do |row|
+          path = row[:attribute_path][:value].to_s
+          next if authorized_for?(row[:readable_by][:value].to_s)
+
+          segments = path.split(".", 2)
+          if segments.size == 1
+            raw = "[redacted]"
+          elsif raw.is_a?(Runtime::Value)
+            raw = raw.with(segments[1], "[redacted]")
+          end
+        end
+
+        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`
+      def marked_paths
+        return @marked_paths if defined?(@marked_paths)
+        return @marked_paths = [] unless @dispatcher.registry.bluebook("Privacy")
+
+        @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
+      def authorized_for?(role)
+        caller = Runtime::Caller.current
+        return false unless caller&.actor_id
+        return false unless @dispatcher.registry.authorization_provider_for(@domain)
+
+        Ports::Authorization.holds_role?(@dispatcher.registry, actor_id: caller.actor_id, role: role,
+                                                                 as_of: caller.as_of, scope: caller.scope)
+      end
+
       def reader?(name)
         !@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 +232,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 +242,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 +254,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