hecks 2.8.0 → 3.0.0

data/lib/hecks/facade/handle.rb

@@ -1,293 +0,0 @@
-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
-    # `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 :
-    #
-    #     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
-        @ir         = aggregate
-        @id         = instance.id
-        @state      = instance.state
-        define_reference_accessors
-        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) = 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.
-      #
-      # @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
-      # 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.
-      #
-      # @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
-
-      def inspect
-        fields = @state.map { |key, value| "#{key}=#{value.inspect}" }.join(" ")
-        "#<#{@ir.hecks_name} #{@id} #{fields}>"
-      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.
-      #
-      # @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 redacted(name) if @state.key?(name) || reader?(name)
-
-        super
-      end
-
-      def respond_to_missing?(name, include_private = false)
-        @state.key?(name) || reader?(name) || super
-      end
-
-      private
-
-      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.
-      #
-      # 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.
-      def define_verb_methods
-        @ir.commands.reject(&:creates?).each do |command|
-          define_singleton_method("#{Naming.snake(command.hecks_name)}!") do |**args|
-            run(command, **args)
-          end
-        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.
-      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.
-      #
-      # 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.
-      def define_reference_accessors
-        @ir.attributes.select(&:reference?).each do |attribute|
-          target = attribute.type.resolve
-          # Cross-domain, or otherwise unresolvable — no accessor rather than a guess.
-          next unless target
-
-          domain     = @domain
-          field      = attribute.name
-          list       = attribute.list?
-          target_fqn = "#{domain}::#{target.hecks_name}"
-
-          define_singleton_method(field) do
-            value = self[field]
-            door = Object.const_get(target_fqn)
-            next Array(value).map { |identity| door.find(identity) } if list
-
-            value && door.find(value)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/hecks/facade/json_door.rb

@@ -1,247 +0,0 @@
-require "json"
-require_relative "handle"
-require_relative "command_request"
-require_relative "../naming"
-require_relative "../runtime/errors"
-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.
-    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`).
-      #
-      # 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 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
-
-        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).
-      #
-      # @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
-
-        "#{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
-      # `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.
-      #
-      # @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)}!" }
-        return wanted if dispatchable.include?(wanted)
-
-        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.
-      #
-      # @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)] }
-        when Array then value.map { |item| deep_symbolize(item) }
-        else value
-        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
-      # `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.
-      #
-      # @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
-      # 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.
-      #
-      # @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
-end