hecks 0.2.0 → 0.3.0

data/lib/hecks/embryonaut_bluebook.rb

@@ -0,0 +1,75 @@
+module Hecks
+  # A VENDORED, EXTERNAL BLUEBOOK — same shape as Framework (framework.rb),
+  # for members that don't ship inside hecks's own lib/ at all: a
+  # separate, independently-versioned package
+  # (github.com/chrisyoung/embryonaut_bluebooks) that a consuming project
+  # vendors into its OWN checkout, the same way a project already vendors
+  # hecks itself (bin/vendor_hecks, vendor/hecks/).
+  #
+  # RECOVERED, NOT REBUILT — this module and its `uses_embryonaut_bluebook`
+  # DSL word (hecksagon_builder.rb) were built on a prior commit of this
+  # repo (933d1dd), vendored out to a real consumer (lifeadelics/domain,
+  # for embryonaut_bluebooks/payments), and then lost from this repo's own
+  # reachable history — a hard reset or rebase left no branch containing
+  # that commit. The lifeadelics vendor snapshot (a `git archive` of that
+  # commit, committed into their repo) was the only surviving copy; this
+  # file is ported forward from it, checked against current `main`'s own
+  # conventions rather than copied wholesale, since the two trees had
+  # otherwise diverged for weeks in both directions.
+  #
+  # RESOLVED FROM THE CONSUMING REGISTRY'S OWN ROOT, not this gem's
+  # __dir__ — Framework::ROOT can be a fixed, `__dir__`-relative constant
+  # because framework members ship inside this gem; an embryonaut bluebook
+  # ships inside the CONSUMER's own checkout instead, at
+  # `<registry.root>/vendor/embryonaut_bluebooks/<name>/bluebook/`. There
+  # is no fixed answer until a registry (and its root) actually exists, so
+  # this resolves lazily, per call — the same reason `uses_framework`
+  # itself only runs at hecksagon-build time, when a real registry is
+  # current.
+  #
+  # EVERY `.bluebook` FILE IN THE PACKAGE, SORTED — not just one. Unlike a
+  # framework member (one file, named by its own stem), a vendored package
+  # can span several bluebook files that reopen the SAME `Hecks.bluebook`
+  # (embryonaut_bluebooks/payments/bluebook/{payment,payments,policies}
+  # .bluebook all reopen "Payments"). Load order matters — policies
+  # .bluebook names `Payment::Succeed` and needs the aggregate already
+  # built — and a plain alphabetical sort already gives the right order:
+  # payment < payments < policies, the same reason that package's own
+  # files are named to fall in that order in the first place.
+  #
+  # ONLY THE BLUEBOOK FILES — same restriction Framework draws, same
+  # reason: a `.hecksagon`/`.port`/`.adapter` is a WIRING decision
+  # (persistence, which processor adapter is bound) that belongs to
+  # whoever is deploying, never baked into the vendored package itself.
+  # embryonaut_bluebooks/payments ships its own mock `.hecksagon` for its
+  # own spec suite; a consumer declares its OWN separate
+  # `Hecks.hecksagon "Payments" do ... end` to bind real storage/adapters
+  # — see Framework's own comment for the fuller reasoning, identical here.
+  #
+  # IDEMPOTENT THE SAME WAY Framework.load! IS — checked against the
+  # bluebook this package actually declares (`Naming.pascal("payments")`
+  # => "Payments"), not a separate ledger. A vendored package's directory
+  # name and its declared `Hecks.bluebook` name are the one convention
+  # this reuses from Framework rather than reinventing.
+  module EmbryonautBluebook
+    def self.load!(name, registry: Hecks.current_registry)
+      unless registry&.root
+        raise Runtime::WiringError,
+              "uses_embryonaut_bluebook(#{name.inspect}) needs a registry with a root to vendor from"
+      end
+
+      return if registry.bluebook(Naming.pascal(name.to_s))
+
+      dir   = File.join(registry.root, "vendor", "embryonaut_bluebooks", name.to_s, "bluebook")
+      files = Dir.glob(File.join(dir, "*.bluebook"))
+
+      if files.empty?
+        raise Runtime::WiringError,
+              "no vendored embryonaut bluebook named #{name.inspect} at #{dir} — " \
+              "run bin/vendor_embryonaut_bluebooks #{name}"
+      end
+
+      files.each { |file| Kernel.load(file) }
+    end
+  end
+end

data/lib/hecks/facade/cli_door.rb

@@ -0,0 +1,116 @@
+require_relative "../runtime/errors"
+
+module Hecks
+  module Facade
+    # THE CLI DOOR — WHERE Facade MEETS A CALLER HOLDING FLAT STRINGS.
+    #
+    # `JsonDoor` beside this one translates for a caller holding parsed JSON:
+    # String keys, already-nested objects, real Integers. A command line has
+    # neither of those. It has `sequence.value=99` — one flat string, with the
+    # nesting spelled as a path and the type not spelled at all.
+    #
+    # So this does the two things that turns into: rebuild the nesting, and
+    # give every leaf the type the chapter declared for it.
+    #
+    # THE TYPE COMES FROM THE PROJECTION, NEVER FROM THE VALUE. A door that
+    # guessed — "99 looks like a number" — would send the Integer 99 for a
+    # version string of "99", and be wrong in a way nothing downstream could
+    # detect, because both are perfectly good arguments. `Projector::CliProjector`
+    # already read the declared field type out of the value object; this only
+    # applies it.
+    module CliDoor
+      module_function
+
+      # `["reference.value=BUG#1", "sequence.value=99"]` against a projected
+      # verb spec -> `{ reference: { value: "BUG#1" }, sequence: { value: 99 } }`
+      def arguments(spec, pairs)
+        # Legacy options are accepted but not printed in help. This lets an
+        # existing id=... aggregate invocation cross the new receiver boundary
+        # while the projected surface teaches to=... exclusively.
+        options = (spec[:arguments] + Array(spec[:legacy_arguments])).to_h do |argument|
+          [argument[:path], argument]
+        end
+
+        pairs.each_with_object({}) do |pair, args|
+          path, value = split(pair)
+          argument    = options[path] || options[expand(path, options)] ||
+                        raise(Runtime::NotFound, unknown(path, options.keys))
+
+          full = options.key?(path) ? path : expand(path, options)
+          next append(args, full.split("."), cast(value, argument[:type])) if argument[:list]
+
+          bury(args, full.split("."), cast(value, argument[:type]))
+        end
+      end
+
+      def split(pair)
+        name, value = pair.split("=", 2)
+        raise Runtime::NotFound, "#{pair.inspect} is not name=value" if value.nil?
+
+        [name, value]
+      end
+
+      # THE SHORT FORM, FOR THE COMMON CASE. Almost every value object in this
+      # corpus has exactly one field, so `reference=BUG#1` is unambiguous and
+      # is what anybody types. Expanded only when precisely one option starts
+      # with that prefix — two would be a guess, and a guess about which field
+      # a caller meant is worse than asking them to say.
+      def expand(path, options)
+        candidates = options.keys.select { |key| key.start_with?("#{path}.") }
+        candidates.length == 1 ? candidates.first : path
+      end
+
+      def cast(value, type)
+        case type
+        when "Integer" then Integer(value)
+        when "Float"   then Float(value)
+        when "Boolean" then %w[true yes 1].include?(value.downcase)
+        else value
+        end
+      rescue ArgumentError
+        raise Runtime::TypeMismatch, "#{value.inspect} is not #{type} — the chapter declares this field as #{type}"
+      end
+
+      # A LIST GROWS RATHER THAN OVERWRITES, and getting this wrong is silent.
+      #
+      # `tags.value=framework tags.value=model-checker` used to reach `bury`
+      # twice and store the second one alone — no refusal, no warning, one tag
+      # simply gone. That is the failure the interview named first: not the
+      # loud kind, the kind where a value is forgotten and the caller has no
+      # way to notice.
+      #
+      # A LIST OF ONE IS STILL A LIST. `tags.value=flaky` produces
+      # `[{ value: "flaky" }]`, not `{ value: "flaky" }`, because the chapter
+      # declared a collection and a caller who sent one element did not
+      # thereby declare a different shape. The old behaviour handed a bare
+      # object to a `list_of` attribute, and everything downstream that walks
+      # it — a query's `contains`, a projection, the Postgres adapter's own
+      # array handling — is entitled to assume it can iterate.
+      #
+      # MULTI-FIELD ELEMENTS ARE NOT SUPPORTED HERE, deliberately. A flat
+      # command line has no way to say which `a.x=` goes with which `a.y=`,
+      # and inventing an index syntax would be a language nobody asked for.
+      # Every list in this corpus is a list of single-field value objects; a
+      # richer one is a job for `JsonDoor`, which has real nesting.
+      def append(hash, path, value)
+        *branches, leaf = path.map(&:to_sym)
+        holder = branches[0..-2].reduce(hash) { |node, key| node[key] ||= {} }
+        list   = holder[branches.last] ||= []
+
+        list << { leaf => value }
+        hash
+      end
+
+      def bury(hash, path, value)
+        *branches, leaf = path.map(&:to_sym)
+        target = branches.reduce(hash) { |node, key| node[key] ||= {} }
+        target[leaf] = value
+        hash
+      end
+
+      def unknown(path, known)
+        "no argument #{path.inspect} — this verb takes #{known.sort.join(', ')}"
+      end
+    end
+  end
+end

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