hecks 0.2.0 → 1.0.0

data/lib/hecks/facade/cli_runner.rb

@@ -0,0 +1,190 @@
+require "json"
+require_relative "cli_door"
+require_relative "command_request"
+require_relative "json_door"
+require_relative "../projector"
+require_relative "../ports/clock"
+
+module Hecks
+  module Facade
+    # THE RUNNER BEHIND A PROJECTED CLI.
+    #
+    # `Projector::CliProjector` answers what a domain's command line LOOKS
+    # like; this is the twenty lines that parse against it and dispatch. It
+    # lives in `lib/` rather than in a `bin/` because more than one front door
+    # wants it — `bin/run` for whichever domain you are standing in, `bin/qc`
+    # pinned to the QA ledger — and a second copy of the parse-and-dispatch
+    # would be the exact duplication the projection exists to avoid.
+    #
+    # NO IO. It answers `[text, status]` and never prints or exits, so a spec
+    # can call it without capturing streams or trapping SystemExit. The `bin/`
+    # scripts do the printing, the same division `Router` and `JsonDoor`
+    # already keep against HTTP.
+    module CliRunner
+      module_function
+
+      # `[text, status]` — status 0 answered, 1 refused or misused.
+      def call(runtime:, argv:, program: "bin/run")
+        bluebook = runtime.registry.bluebooks.values.first
+        cli      = Projector.call(:cli, bluebook: bluebook, options: { program: program })
+
+        name = argv.first
+        return [cli[:usage], 0] if name.nil? || %w[--help -h help].include?(name)
+
+        # `ask` PUTS A QUESTION IN ITS OWN NAMESPACE — a chapter may declare a
+        # command and a query of one name, and banking does.
+        asking = name == "ask"
+        argv   = argv[1..] if asking
+        name   = argv.first
+        return [cli[:usage], 1] if name.nil?
+
+        # RESOLVED THROUGH THE ALIAS MAP, so `pizzas create_pizza` and
+        # `pizzas order.create_pizza` reach the same verb — the aggregate is
+        # worth typing only when two of them declare the same word.
+        pool = asking ? cli[:questions] : cli[:verbs]
+        key  = cli[:names][asking ? :question : :command][name]
+        spec = pool[key]
+        return [unknown(cli, name, asking, program), 1] unless spec
+
+        rest = argv[1..]
+        if rest.include?("--help")
+          help = Projector.call(:cli, bluebook: bluebook,
+                                      options:  { program: program, verb: name, ask: asking })[:usage]
+          return [help, 0]
+        end
+
+        dispatch(runtime, spec, name, rest, program, asking)
+      end
+
+      def dispatch(runtime, spec, name, rest, program, asking)
+        args = stamp_time(runtime, spec, CliDoor.arguments(spec, rest))
+
+        if spec[:kind] == :query
+          rows = runtime.query(spec[:verb], **args)
+          return [JSON.pretty_generate(rows.map { |row| JsonDoor.materialize(row) }), 0]
+        end
+
+        # THE ANSWER IS SCOPED TO WHAT WAS ASKED. `bin/run`'s step-list form
+        # reports the whole store because a corpus run is judged on all of it;
+        # somebody who issued one verb wants that verb's outcome, and against a
+        # Postgres-backed domain the full dump is every record there has been.
+        request = CommandRequest.normalize(args, receiver:        spec[:receiver],
+                                                 legacy_receiver: spec[:legacy_receiver])
+        handle = runtime.dispatch(spec[:verb], **request)
+        return [JSON.pretty_generate(answered(handle)), 0] if handle.state.nil?
+
+        [JSON.pretty_generate(id:     handle.id,
+                              state:  JsonDoor.materialize(handle.state),
+                              events: handle.events.map(&:name)), 0]
+      rescue Runtime::NotFound, Runtime::TypeMismatch => e
+        # A BAD ARGUMENT AND A MISSING RECORD BOTH LAND HERE, and both want the
+        # same next step: read what the verb actually takes.
+        ["#{e.message}\n\n  #{program} #{asking ? 'ask ' : ''}#{name} --help", 1]
+      rescue *Runtime::DOMAIN_REFUSALS => e
+        # THE REFUSAL IS THE PRODUCT — the chapter's own sentence, verbatim.
+        [e.message, 1]
+      end
+
+      # THE CLOCK, FILLED IN AT THE DOOR.
+      #
+      # A staleness rule needs the time, and the sublanguage cannot ask for it
+      # — a `given` that read the clock would judge the same record differently
+      # on two runs, and every replay, audit and fuzz oracle here assumes it
+      # does not. So `now` stays an ARGUMENT the predicate merely reads, and
+      # the question becomes who types it. Before this, the caller did:
+      #
+      #   qa/quality_control target.claim id=QC held_by.value=me \
+      #     now.value=$(date +%s) window.value=900
+      #
+      # which is a shell incantation in front of every claim, and one an agent
+      # gets wrong by pasting a stale number.
+      #
+      # AT THE DOOR, NOT IN THE RUNTIME, and the distinction is load-bearing.
+      # `Ports::IdentityGeneration` reasons the same question through for a
+      # minted uuid and lands on "the value is baked into the caller's args at
+      # the first live dispatch". A clock consulted INSIDE the interpreter
+      # would not have that property — a recorded corpus step replayed
+      # tomorrow would quietly get tomorrow's time, and the fuzzer's oracle and
+      # the adapter-agreement gate both compare runs of exactly that shape. Here
+      # it fills only what a person or an agent is typing, and `runtime.dispatch`
+      # is left alone.
+      #
+      # AN EXPLICIT VALUE ALWAYS WINS, so a spec or a caller reproducing a
+      # moment says so and is believed. This only supplies what was omitted.
+      #
+      # BY NAME, WHICH IS THE ONE UNCOMFORTABLE PART. `now` is a plausible
+      # domain word and nothing declares that it means the clock. It is
+      # tolerable because this is a convenience layer rather than semantics —
+      # the verb's own help says the argument exists, dispatch is unchanged,
+      # and passing it explicitly is always available. The honest version is a
+      # declaration in the chapter (`attribute :now, Instant, from: :clock`),
+      # which is a language change: DSL, IR, the self-hosted grammar and its
+      # goldens. Worth doing; not worth smuggling in here.
+      def stamp_time(runtime, spec, args)
+        return args unless spec[:arguments].any? { |argument| argument[:path].start_with?("now.") }
+        return args if args.key?(:now)
+
+        args.merge(now: { value: Ports::Clock.now(runtime.registry) })
+      end
+
+      # A PORT OPERATION HAS NO STATE, AND ITS PAYLOAD IS THE ENTIRE POINT.
+      #
+      # A command answers with the record it changed, so naming the events is
+      # enough — the interesting part is in `state`. A port operation changes
+      # no record: it asked something outside and came back with what was
+      # said, and that lives ONLY in the event payload. Reporting names alone
+      # would print `SpecsCompleted` and drop the spec output on the floor.
+      #
+      # This is what makes a projected CLI usable as somebody's only door. An
+      # agent that may not shell out cannot run `rspec` and read the terminal;
+      # it asks the port and reads the answer, and if the answer is a bare
+      # event name then the door leads nowhere and it needs a shell after all.
+      #
+      # BOTH ENDINGS COME BACK THE SAME WAY, and the status stays 0 for both.
+      # A refusal here is not a misuse — `IssueStillOpen` and `SuiteFailed`
+      # are answers the caller asked for, correctly delivered. Exit 1 is for
+      # "you typed something wrong", and conflating the two would have a
+      # scripted agent treat a healthy no as a broken call.
+      def answered(handle)
+        # THE ID COMES OFF THE EVENT, because a port operation hydrates no
+        # instance and the handle's own `id` is nil by design. The event knows
+        # which record was asked about — it was stamped with it — and printing
+        # `null` beside a payload that plainly says `SW-TOOL` would read as a
+        # bug in something.
+        { id:     handle.id || handle.events.first&.id,
+          events: handle.events.map do |event|
+            { name: event.name, payload: JsonDoor.materialize(event.payload) }
+          end }
+      end
+
+      # A NEAR MISS IS WORTH MORE THAN A LIST. Somebody who typed
+      # `bug.discovr` wants one line, not eighty-seven of them.
+      #
+      # RANKED BY SHARED PREFIX, not by substring. Substring was the first
+      # attempt and it finds nothing for the commonest typo of all — a dropped
+      # letter, `order.create_piza`, which is a substring of nothing. Prefix
+      # length survives an error anywhere after it, which is where errors are.
+      def unknown(cli, name, asking, program)
+        # BOTH SPELLINGS ARE CANDIDATES. A caller who typed the qualified
+        # form with a typo — `order.create_piza` — shares no prefix with the
+        # short name `create_pizza`, so pooling only one of them suggests
+        # nothing for half the mistakes anybody makes.
+        pool = cli[:names][asking ? :question : :command].keys
+        near = pool.map    { |candidate| [shared_prefix(candidate, name), candidate] }
+                   .select { |shared, _| shared >= [name.length / 2, 3].max }
+                   .sort_by { |shared, candidate| [-shared, candidate] }
+                   .map(&:last)
+
+        lines = ["no such #{asking ? 'question' : 'verb'}: #{name}"]
+        lines += ["", "did you mean:", *near.first(5).map { |candidate| "  #{candidate}" }] unless near.empty?
+        lines += ["", "  #{program}#{asking ? ' ask' : ''}   for the full list"]
+        lines.join("\n")
+      end
+
+      def shared_prefix(one, other)
+        length = [one.length, other.length].min
+        (0...length).find { |index| one[index] != other[index] } || length
+      end
+    end
+  end
+end

data/lib/hecks/facade/command_request.rb

@@ -0,0 +1,105 @@
+require_relative "../runtime/errors"
+
+module Hecks
+  module Facade
+    # Turns an external command request into the dispatcher's receiver/payload
+    # envelope. Human-facing doors may accept their old flat id spelling at
+    # the edge, but every call leaving this boundary has one shape:
+    #
+    #   aggregate command: { to: "record-id", with: { declared: "facts" } }
+    #   entity command:    { to: { aggregate: "...", entity: "..." },
+    #                        with: { declared: "facts" } }
+    #
+    # The command interpreter remains the authority on which facts are
+    # declared. This helper only prevents routing fields from leaking into the
+    # fact payload and gives every external door the same wire contract.
+    module CommandRequest
+      module_function
+
+      def normalize(input, receiver:, legacy_receiver: nil)
+        request = symbolize(input)
+        unless request.is_a?(Hash)
+          raise Runtime::TypeMismatch, "a command request must be a hash"
+        end
+
+        route, facts = split(request, receiver: receiver, legacy_receiver: legacy_receiver)
+        validate_route!(route, receiver)
+
+        envelope = { with: facts }
+        envelope[:to] = route if receiver
+        envelope
+      end
+
+      def split(request, receiver:, legacy_receiver:)
+        if request.key?(:with)
+          loose = request.keys - [:to, :with]
+          unless loose.empty?
+            raise Runtime::TypeMismatch,
+                  "an explicit command envelope takes routing in to: and facts in with:, not loose #{loose.sort.join(', ')}"
+          end
+
+          facts = request[:with]
+          raise Runtime::TypeMismatch, "with: must be a hash of command facts" unless facts.is_a?(Hash)
+
+          return [request[:to], facts]
+        end
+
+        flat  = request.dup
+        route = flat.delete(:to)
+        route = take_legacy_route(flat, receiver, legacy_receiver) if route.nil?
+        [route, flat]
+      end
+      private_class_method :split
+
+      def take_legacy_route(flat, receiver, legacy_receiver)
+        return unless legacy_receiver
+
+        if receiver == :aggregate
+          return flat.delete(legacy_receiver.to_sym)
+        end
+
+        return unless receiver == :entity && legacy_receiver.is_a?(Hash)
+
+        aggregate_key = legacy_receiver.fetch(:aggregate).to_sym
+        entity_key    = legacy_receiver.fetch(:entity).to_sym
+        return unless flat.key?(aggregate_key) || flat.key?(entity_key)
+
+        { aggregate: flat.delete(aggregate_key), entity: flat.delete(entity_key) }
+      end
+      private_class_method :take_legacy_route
+
+      def validate_route!(route, receiver)
+        case receiver
+        when nil
+          raise Runtime::TypeMismatch, "this command does not take a receiver in to:" unless route.nil?
+        when :aggregate
+          if route.nil? || route.to_s.empty? || route.is_a?(Hash)
+            raise Runtime::TypeMismatch, "to: must name the receiving aggregate identity"
+          end
+        when :entity
+          unless route.is_a?(Hash)
+            raise Runtime::TypeMismatch, "to: for an entity command must contain aggregate: and entity:"
+          end
+
+          extra = route.keys - [:aggregate, :entity]
+          missing = [:aggregate, :entity].select { |key| route[key].nil? || route[key].to_s.empty? }
+          unless extra.empty? && missing.empty?
+            raise Runtime::TypeMismatch, "to: for an entity command must contain only aggregate: and entity:"
+          end
+        else
+          raise ArgumentError, "unknown receiver kind #{receiver.inspect}"
+        end
+      end
+      private_class_method :validate_route!
+
+      def symbolize(value)
+        case value
+        when Hash then value.to_h { |key, nested| [key.to_sym, symbolize(nested)] }
+        when Array then value.map { |nested| symbolize(nested) }
+        else value
+        end
+      end
+      private_class_method :symbolize
+    end
+  end
+end

data/lib/hecks/facade/handle.rb

@@ -0,0 +1,173 @@
+require_relative "../naming"
+
+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. 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.
+    #
+    # A non-creating verb is a method returning self, so commands chain :
+    #
+    #     Pizza.create_pizza(...).add_topping(...).purchase(...)
+    class Handle
+      attr_reader :id
+
+      def initialize(dispatcher:, domain:, ir:, instance:)
+        @dispatcher = dispatcher
+        @domain     = domain
+        @ir         = ir
+        @id         = instance.id
+        @state      = instance.state
+        define_reference_accessors
+        define_verb_methods
+      end
+
+      def [](key) = @state[key.to_sym]
+
+      # `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 }` 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,
+      # 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)
+
+      def fqn = "#{@domain}::#{@ir.hecks_name}"
+
+      def events
+        @dispatcher.events.select { |event| event.aggregate == fqn && event.id == @id }
+      end
+
+      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. The old door said this with `other.is_a?(self.class)`,
+      # leaning on one class per aggregate ; the fqn says it in data.
+      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
+
+      # A declared field not yet written arrives here too (nil, the way a
+      # defined reader answered). Verbs are NOT handled here — see
+      # `define_verb_methods` for why.
+      def method_missing(name, *args, **kwargs, &block)
+        return @state[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)
+
+      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 —
+      # 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
+      # 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 — 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.
+      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
+
+          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

@@ -0,0 +1,166 @@
+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 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".
+    #
+    # 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`.
+    #
+    # 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
+
+      # "Banking", "Customer" -> the `Banking::Customer` class `.find` /
+      # `.create_...` / etc already answer for — the same class
+      # `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.
+      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
+
+      # 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
+      # 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).
+      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
+
+      # 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 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
+      # `Handle` itself applies, is what keeps "accepted here" and
+      # "dispatchable there" the same set.
+      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
+
+      # `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.
+      def find!(klass, id)
+        klass.find(id) or raise Runtime::NotFound, "no #{klass.ir.hecks_name} found for id #{id.inspect}"
+      end
+
+      # 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.
+      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
+
+      # 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.
+      def materialize(value)
+        value = value.to_h if value.is_a?(Handle)
+        Runtime::Value.materialize(value)
+      end
+
+      # 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.
+      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
+
+      # 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.
+      def parse(raw_json) = JSON.parse(raw_json)
+    end
+  end
+end