hecks 0.2.0 → 0.3.0

data/lib/hecks/query_specification/common/inspection_spec.rb

@@ -0,0 +1,9 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      InspectionSpec = Struct.new(:mode, keyword_init: true) do
+        def to_h = { mode: mode.to_s }
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/common/limit_spec.rb

@@ -0,0 +1,9 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      LimitSpec = Struct.new(:value, keyword_init: true) do
+        def to_h = { value: QuerySpecification.render_value(value) }
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/common/null_policy.rb

@@ -0,0 +1,80 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      module NullPolicy
+        module_function
+
+        # STABLE on purpose : rows arrive already in identity order from
+        # Ports::Query::Ordering, and that base is what makes a tie deterministic
+        # rather than store-dependent. A plain sort_by is not stable in Ruby, so
+        # equal keys would shuffle and the identity tier would be lost exactly
+        # where it is needed. Descending reverses both partitions, so a tie reads
+        # identity-descending too — the same total order sql_order renders as
+        # `field DESC, id DESC`.
+        def order(records, direction:, policy: nil, &key)
+          null_rows, valued_rows = records.partition { |record| key.call(record).nil? }
+          sorted = valued_rows.each_with_index.sort_by { |record, index| [key.call(record), index] }.map(&:first)
+          if direction.to_s == "desc"
+            sorted.reverse!
+            null_rows.reverse!
+          end
+          case policy&.mode.to_s
+          when "first" then null_rows + sorted
+          when "last" then sorted + null_rows
+          else direction.to_s == "desc" ? sorted + null_rows : null_rows + sorted
+          end
+        end
+
+        def sql_order(expression, direction, policy)
+          direction = direction.to_s.downcase == "desc" ? "DESC" : "ASC"
+          nulls = case policy&.mode.to_s
+                  when "first" then " NULLS FIRST"
+                  when "last" then " NULLS LAST"
+                  else ""
+                  end
+          "#{expression} #{direction}#{nulls}, id #{direction}"
+        end
+
+        # THE COMPARATORS A NULL CANNOT SATISFY — the other half of
+        # `sql_predicate` below. That one answers "the value COMPARED TO is
+        # null" (`eq: nil` -> IS NULL, `ne: nil` -> IS NOT NULL, a real
+        # convention both adapters already shared). This one answers the
+        # case nothing covered: the ROW'S OWN value is null and the value
+        # compared to is not.
+        #
+        # SQL says unknown. `NULL <> 'red'` is NULL, not true, so the row
+        # is not returned. Ruby says `nil != "red"` is true, so it is. The
+        # two adapters therefore answered the SAME query on the SAME data
+        # differently — Memory returning a row SQLite omitted — which is
+        # not a difference of opinion a caller can plan around.
+        #
+        # Resolved toward SQL, and not because SQL is the store: an absent
+        # or null field is UNKNOWN, not a value, and a comparison against
+        # unknown is unknown rather than true. Making SQL match Ruby
+        # instead would mean compiling every `ne:` to
+        # `(col <> $1 OR col IS NULL)` — more to get right in two
+        # dialects, and a reliable way to lose an index — to make a real
+        # query engine agree with an in-memory one.
+        #
+        # `none_in_state` is deliberately NOT here: it is a 9th, vendored
+        # comparator whose `held` is a reference id, and a row holding no
+        # reference is genuinely "not in that state" rather than unknown.
+        NULL_UNMATCHABLE = %w[eq ne lt lte gt gte in contains].freeze
+
+        def unmatchable?(operation, held, want)
+          held.nil? && !want.nil? && NULL_UNMATCHABLE.include?(operation.to_s)
+        end
+
+        def sql_predicate(expression, operation, value)
+          if value.nil? && operation.to_s == "eq"
+            ["#{expression} IS NULL", []]
+          elsif value.nil? && operation.to_s == "ne"
+            ["#{expression} IS NOT NULL", []]
+          else
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/common/null_semantics.rb

@@ -0,0 +1,11 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      NullSemantics = Struct.new(:mode, keyword_init: true) do
+        def to_h = { mode: mode.to_s }
+
+        def self.default = new(mode: :native)
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/common/offset_spec.rb

@@ -0,0 +1,9 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      OffsetSpec = Struct.new(:value, keyword_init: true) do
+        def to_h = { value: QuerySpecification.render_value(value) }
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/common/options.rb

@@ -0,0 +1,32 @@
+require_relative "null_semantics"
+
+module Hecks
+  module QuerySpecification
+    module Common
+      class Options
+        attr_reader :wheres, :order_by, :limit, :offset, :cursor,
+                    :authorization, :null_semantics, :inspection
+
+        def initialize(wheres: [], order_by: nil, limit: nil, offset: nil, cursor: nil,
+                       authorization: nil,
+                       inspection: nil, null_semantics: NullSemantics.default)
+          @wheres, @order_by, @limit, @offset, @cursor = wheres, order_by, limit, offset, cursor
+          @authorization, @null_semantics, @inspection = authorization, null_semantics, inspection
+        end
+
+        def options_to_h
+          { wheres: @wheres.map(&:to_h), order_by: @order_by&.to_h, limit: @limit&.to_h,
+            offset: @offset&.to_h, cursor: @cursor&.to_h, authorization: @authorization&.to_h,
+            null_semantics: @null_semantics&.to_h, inspection: @inspection&.to_h }
+        end
+
+        def extra_options_to_h
+          options_to_h.reject { |key, value|
+            value.nil? || value == [] || (key == :null_semantics && value == { mode: "native" })
+          }
+                      .reject { |key, _| %i[wheres order_by limit].include?(key) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/common/order_by.rb

@@ -0,0 +1,9 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      OrderBy = Struct.new(:field, :direction, keyword_init: true) do
+        def to_h = { field: field.to_s, direction: direction.to_s }
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/common/specification.rb

@@ -0,0 +1,10 @@
+require_relative "comparators"
+require_relative "where_clause"
+require_relative "order_by"
+require_relative "limit_spec"
+require_relative "offset_spec"
+require_relative "cursor_spec"
+require_relative "authorization_spec"
+require_relative "null_semantics"
+require_relative "inspection_spec"
+require_relative "options"

data/lib/hecks/query_specification/common/where_clause.rb

@@ -0,0 +1,9 @@
+module Hecks
+  module QuerySpecification
+    module Common
+      WhereClause = Struct.new(:field, :op, :value, keyword_init: true) do
+        def to_h = { field: field.to_s, op: op.to_s, value: QuerySpecification.render_value(value) }
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/field_path.rb

@@ -0,0 +1,89 @@
+module Hecks
+  module QuerySpecification
+    # ONE reading of a dotted query-field path, shared by every place that
+    # used to invent its own. The reference interpreter did a bare
+    # `record[field]` lookup (a dotted path silently matched nothing), the
+    # SQL side split dots but judged numericness from the FIRST nested
+    # segment only (a two-level path quietly compared text), and the build
+    # seal walked the declaration graph a third way. Three
+    # implementations of "what does pizza.price_cents.cents mean" is two
+    # more than a language gets to have.
+    #
+    # Two sides, deliberately in one file so they cannot drift:
+    #
+    #   dig(holder, field)        — VALUE side: walk a record's held state,
+    #                               segment by segment, through Value
+    #                               objects and plain hashes alike.
+    #   leaf_attribute / numeric? — DECLARATION side: walk the declared
+    #                               shape to the attribute a path lands on.
+    #                               Callers supply value-object lookup as a
+    #                               block, because an Aggregate and a
+    #                               mid-build AggregateBuilder hold their
+    #                               shapes differently but walk the same.
+    module FieldPath
+      module_function
+
+      NUMERIC_PRIMITIVES = %w[Integer Float].freeze
+      SCALAR_PRIMITIVES  = %w[String Integer Float TrueClass FalseClass].freeze
+
+      # The held value a dotted field names, or nil — never a raise. The
+      # first segment reads off the record (an Instance, a Value, or a
+      # plain row hash); the rest read through whatever each step holds. A
+      # stored nested value object is a plain hash by the time it is read
+      # back, keyed by symbol in memory and by string off a wire decode,
+      # so both spellings are tried.
+      def dig(holder, field)
+        return nil if field.nil?
+
+        field.to_s.split(".").reduce(holder) { |current, segment| read(current, segment) }
+      end
+
+      def read(current, segment)
+        return nil if current.nil?
+        return current[segment.to_sym] || current[segment] if current.is_a?(Hash)
+
+        current[segment]
+      end
+
+      # The declared attribute a path lands on, or nil. `segments` is the
+      # dotted tail — for a bare field it is empty and the root attribute
+      # is its own leaf. The walk stops dead at a reference (an id is a
+      # scalar; nothing nests under it) and at any member the declared
+      # value object does not carry.
+      def leaf_attribute(attribute, segments)
+        current = attribute
+        segments.each do |segment|
+          return nil if current.nil? || current.reference?
+
+          shape = yield(current.type.to_s)
+          current = shape&.attributes&.find { |member| member.name.to_s == segment }
+        end
+        current
+      end
+
+      # May an ordered comparator (lt/lte/gt/gte) land here, and may an
+      # ORDER BY cast here numerically? A bare field keeps the one-level
+      # convention every adapter already implements: a numeric primitive,
+      # or a value object carrying at least one numeric member. A dotted
+      # path must land on a numeric primitive itself — the convention does
+      # not reach through a named path, it IS the absence of one.
+      def numeric?(attribute, segments, &value_object)
+        leaf = leaf_attribute(attribute, segments, &value_object)
+        return false if leaf.nil? || leaf.list? || leaf.reference?
+        return true if NUMERIC_PRIMITIVES.include?(leaf.type.to_s)
+        return false unless segments.empty?
+
+        shape = yield(leaf.type.to_s)
+        !shape.nil? && shape.attributes.any? { |member| NUMERIC_PRIMITIVES.include?(member.type.to_s) }
+      end
+
+      # A dotted path must end on a SCALAR member — landing on a value
+      # object would hand SQL a JSON object where the reference
+      # interpreter unwraps a hash, and the two would answer differently.
+      def scalar_leaf?(attribute, segments, &value_object)
+        leaf = leaf_attribute(attribute, segments, &value_object)
+        !leaf.nil? && !leaf.list? && !leaf.reference? && SCALAR_PRIMITIVES.include?(leaf.type.to_s)
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/hop_path.rb

@@ -0,0 +1,130 @@
+require_relative "../naming"
+
+module Hecks
+  module QuerySpecification
+    # ONE reading of a dotted query-field path that hops THROUGH a
+    # reference into another aggregate's own shape — FieldPath's
+    # sibling, not its member. FieldPath walks a SHAPE, which cannot
+    # loop, and answers nil, never raising, because there is nothing
+    # left to say beyond "not found." HopPath walks the REFERENCE
+    # GRAPH instead, which the language does not guarantee acyclic —
+    # aggregates only refuse a DIRECT bidirectional pair
+    # (BluebookBuilder#validate_no_bidirectional_references! explicitly
+    # declines to take a position on a longer ring) — so a walk here
+    # needs to say WHY it stopped, not just that it did.
+    #
+    # Every method below takes an ATTRIBUTE ARRAY, never a "shape"
+    # object — deliberately, because the two real callers hold their
+    # attributes differently. `AggregateBuilder` (tier-1 seal, mid-
+    # build) exposes `attributes` as a plain reader, but its own
+    # `attribute(name, type = String, ...)` is the DSL's attribute-
+    # DECLARING method — calling it as a finder would silently mint a
+    # new String attribute instead of looking one up. A sealed
+    # `Aggregate` (tier-2 seal, and every runtime target) has a
+    # real `attribute(name)` finder, but taking the array either way
+    # sidesteps the mismatch instead of asking every caller to know
+    # which kind of object it holds.
+    module HopPath
+      module_function
+
+      Hop = Struct.new(:attribute, :target_name, :target, keyword_init: true)
+
+      # refusal: nil (clean), :unresolvable (a hop's target cannot be
+      # found — cross-domain, or simply not declared in this chapter),
+      # :too_deep (see MAX_HOPS below).
+      Plan = Struct.new(:hops, :tail, :refusal, keyword_init: true)
+
+      # A hop chain long enough to matter is long enough to be a
+      # mistake — NOT a guard against a walk that cannot terminate.
+      # Nothing here loops forever regardless of how the reference
+      # graph is shaped: a hop chain is a literal dotted string, fixed
+      # at declaration time, and every step consumes exactly one of
+      # its own segments — the walk is bounded by what was TYPED, not
+      # by the graph. A self-referential aggregate hopping through
+      # itself more than once (`"parent.parent.name"`, a grandparent
+      # query) is real, common, and perfectly safe; this exists only
+      # to refuse a chain nobody meant to write this long.
+      MAX_HOPS = 8
+
+      # The segment name a Reference answers to in a hop path — its own
+      # declared attribute name, unchanged (ADR 0025, "References":
+      # `reference_to` mints that bare name now, no `_id`, so there is
+      # no derivation left to apply). `proposal/client` (a query hop)
+      # and `proposal.client` (the Ruby accessor,
+      # `Facade::Handle#define_reference_accessors`) name the same
+      # concept the same way.
+      def hop_name(attribute) = attribute.name.to_s
+
+      # Does this path's HEAD cross into another record via `/`? THE
+      # OPERATOR IS THE ANSWER NOW, not a name collision to arbitrate —
+      # `.` walks fields inside this record, `/` crosses into another
+      # one, so a path with no `/` is never a hop, full stop, and the
+      # OLD "a real local attribute wins first" rule (needed only
+      # because `.` was overloaded for both meanings, and `client_id`
+      # vs `client` was how the two were told apart) has nothing left
+      # to arbitrate. Answerable from `attributes` alone — a Reference
+      # knows its own `target_name` at declaration, before it can
+      # `resolve` it — which is what lets the AGGREGATE seal recognise
+      # a hop it cannot yet check.
+      def hop_head?(field, attributes)
+        head, rest = field.to_s.split("/", 2)
+        return false unless rest
+
+        attributes.any? { |candidate| candidate.reference? && hop_name(candidate) == head }
+      end
+
+      # ONE STEP: does `field`'s head hop through one of `attributes`'
+      # own references? Answers the resolved `Hop` plus the string
+      # still left to walk (itself possibly another `/`-hop, against
+      # the TARGET's own attributes, or a plain `.`-dotted field walk
+      # once the hops run out) — or nil, when the head names nothing or
+      # the path has no `/` at all. This is the one primitive
+      # Runtime::ReferenceHop needs: it recurses hop by hop through its
+      # own `apply`, one ordinary same-aggregate query at a time, and
+      # never needs the whole chain resolved up front the way a seal
+      # does.
+      def next_hop(field, attributes)
+        head, rest = field.to_s.split("/", 2)
+        return nil unless rest
+
+        attribute = attributes.find { |candidate| candidate.reference? && hop_name(candidate) == head }
+        return nil unless attribute
+
+        hop = Hop.new(attribute: attribute, target_name: attribute.type.target_name, target: attribute.type.resolve)
+        [hop, rest]
+      end
+
+      # The WHOLE chain, resolved — every hop's target found, in
+      # order — for the one caller that needs it all at once:
+      # BluebookBuilder#validate_query_hops!, checking a hop chain
+      # before anything ever dispatches it.
+      def plan(field, attributes)
+        hops = []
+        remaining = field.to_s
+        current = attributes
+
+        loop do
+          step = next_hop(remaining, current)
+          break unless step
+
+          hop, rest = step
+          return Plan.new(hops: hops, tail: nil, refusal: :too_deep) if hops.size >= MAX_HOPS
+
+          # Pushed even unresolved — a caller reporting :unresolvable
+          # needs THIS hop's own target_name (real, known at
+          # declaration, regardless of whether resolve succeeded), not
+          # whatever hop came before it. `.target` is nil on this one
+          # entry; every caller checking `hops.last.target` already has
+          # to handle that, the same way `next_hop`'s own caller does.
+          hops << hop
+          return Plan.new(hops: hops, tail: nil, refusal: :unresolvable) unless hop.target
+
+          current = hop.target.attributes
+          remaining = rest
+        end
+
+        Plan.new(hops: hops, tail: remaining, refusal: nil)
+      end
+    end
+  end
+end

data/lib/hecks/query_specification/read_model/specification.rb

@@ -0,0 +1,18 @@
+require_relative "../common/options"
+
+module Hecks
+  module QuerySpecification
+    module ReadModel
+      class Specification < Common::Options
+        attr_reader :joins
+
+        def initialize(joins: [], **options)
+          super(**options)
+          @joins = joins
+        end
+
+        def to_h = options_to_h.merge(joins: @joins)
+      end
+    end
+  end
+end

data/lib/hecks/query_specification.rb

@@ -0,0 +1,14 @@
+module Hecks
+  # The declarative shape of an ask — what a query says, held apart from
+  # any engine that answers it. `common/` is the vocabulary every ask
+  # shares; `read_model/` the read-model-specific specification.
+  module QuerySpecification
+  end
+end
+
+require_relative "query_specification/common/specification"
+require_relative "query_specification/common/null_policy"
+require_relative "query_specification/common/dsl"
+require_relative "query_specification/field_path"
+require_relative "query_specification/hop_path"
+require_relative "query_specification/read_model/specification"

data/lib/hecks/rendering.rb

@@ -0,0 +1,48 @@
+require "json"
+
+module Hecks
+  # HOW A VALUE READS INSIDE A REFUSAL, in one place, because a refusal is an
+  # ANSWER and its wording is contract — pinned byte-for-byte by the corpus.
+  #
+  # `inspect` and JSON agree on scalars and disagree on everything composite :
+  # a hash is `{"cents"=>100}` against `{"cents":100}`, an array is `["a", "b"]`
+  # against `["a","b"]`. Each such spelling is invisible until a composite
+  # actually reaches a message, which is why both known cases were found by
+  # something deliberately passing the wrong shape rather than by review — the
+  # first by hand in spec/corpus/banking.json, the second by bin/fuzz, at a
+  # different site, after the first was patched where it was found.
+  #
+  # So it lives here rather than in whichever file noticed it, and the house style
+  # is JSON because that is what every other refusal in the corpus already prints.
+  module Rendering
+    module_function
+
+    def describe(value)
+      case value
+      when nil then "nil"
+      when Hash, Array then JSON.generate(value)
+      else
+        # A Hecks::Runtime::Value reaching a refusal message (an
+        # arithmetic op's own `amount`/`current`, an Admissibility
+        # `current`, ...) had no case here, falling straight through to
+        # Ruby's own #inspect and leaking a raw object pointer
+        # ("#<Hecks::Runtime::Value:0x...>") into an otherwise
+        # correct domain refusal. Duck-typed on `respond_to?(:to_h)`
+        # rather than naming `Runtime::Value` directly — `Runtime::Value`
+        # itself requires THIS file (`runtime/value.rb`'s own
+        # `require_relative "../rendering"`), so naming it here would be
+        # circular. A single-field wrapper (the overwhelming common case
+        # — an amount, an id, a lifecycle field) unwraps to its bare
+        # scalar, described recursively; a genuinely multi-field value
+        # renders as its fields' JSON, same as a bare Hash already does
+        # two lines up.
+        if value.respond_to?(:to_h) && !value.is_a?(Hash) && !value.is_a?(Array)
+          fields = value.to_h
+          fields.size == 1 ? describe(fields.values.first) : JSON.generate(fields)
+        else
+          value.inspect
+        end
+      end
+    end
+  end
+end

data/lib/hecks/router/namespace_installer.rb

@@ -0,0 +1,157 @@
+require_relative "../fqn"
+require_relative "../facade/handle"
+
+module Hecks
+  class Router
+    # Installs optional Ruby syntax over an already-loaded router. FQN
+    # resolution stays in Router; this object only adapts it to constants and
+    # method calls.
+    class NamespaceInstaller
+      class OptionsProxy
+        def initialize(router:, realm:, domain:, aggregate:, options:)
+          unknown = options.keys - [:version]
+          raise ArgumentError, "unknown router options: #{unknown.join(', ')}" unless unknown.empty?
+
+          @router, @realm, @domain, @aggregate = router, realm, domain, aggregate
+          @version = options[:version]&.to_s
+        end
+
+        def method_missing(verb, **args)
+          fqn = fqn_for(verb)
+          fqn.command? ? @router.dispatch(fqn.to_s, **args) : @router.query(fqn.to_s, **args)
+        end
+
+        def respond_to_missing?(verb, include_private = false)
+          Fqn.command_name?(verb) || Fqn.query_name?(verb) || super
+        end
+
+        private
+
+        def fqn_for(verb)
+          if Fqn.command_name?(verb)
+            Fqn.command(realm: @realm, domain: @domain, version: @version, aggregate: @aggregate, command: verb)
+          elsif Fqn.query_name?(verb)
+            Fqn.query(realm: @realm, domain: @domain, version: @version, aggregate: @aggregate, query: verb)
+          else
+            raise NoMethodError, "#{verb.inspect} is not a Bluebook command or query"
+          end
+        end
+      end
+
+      def initialize(router)
+        @router = router
+      end
+
+      def install!
+        current_entries.each { |entry| install_namespace_entry(entry) }
+        install_shortcuts!
+        install_aggregate_doors!
+        self
+      end
+
+      private
+
+      attr_reader :router
+
+      def current_entries = router.available.reject { |entry| entry.fqn.version }
+
+      def install_namespace_entry(entry)
+        target  = namespace_for(entry.fqn.realm, entry.fqn.domain, entry.fqn.aggregate)
+        address = entry.fqn.to_s
+        active_router = router
+        target.define_singleton_method(:options) do |**options|
+          OptionsProxy.new(router: active_router, realm: entry.fqn.realm, domain: entry.fqn.domain,
+                           aggregate: entry.fqn.aggregate, options: options)
+        end
+        if entry.command?
+          target.define_singleton_method(entry.fqn.verb) { |**args| active_router.dispatch(address, **args) }
+        else
+          target.define_singleton_method(entry.fqn.verb) { |**args| active_router.query(address, **args) }
+        end
+      end
+
+      # `.find`/`.all`/`.count`/`.events`/`.repository` — the SAME read/CRUD
+      # surface `Facade::Surface::AggregateDoor` gives a plain `Hecks
+      # .boot`, missing here until now: `install_namespace_entry` above
+      # installs ONE method per declared VERB, so an aggregate with no
+      # commands or queries of its own shape (or simply never asked for
+      # a `find`-shaped query) had no way to look up one record by id
+      # through the router surface at all — real gap, hit live building
+      # a `List` aggregate meant to be read this way. Grouped by
+      # (realm, domain, aggregate) rather than installed per-verb,
+      # because unlike a command or query this is the SAME five methods
+      # regardless of which verb happened to trigger this aggregate's
+      # own namespace module into existing.
+      def install_aggregate_doors!
+        current_entries.reject { |entry| entry.fqn.aggregate.nil? }
+                       .group_by { |entry| [entry.fqn.realm, entry.fqn.domain, entry.fqn.aggregate] }
+                       .each_value { |entries| install_aggregate_door(entries.first) }
+      end
+
+      def install_aggregate_door(entry)
+        dispatcher = entry.dispatcher
+        domain     = entry.fqn.domain
+        ir         = dispatcher.registry.bluebook(domain)&.aggregate(entry.fqn.aggregate)
+        return unless ir # a query/command-only entry whose owner isn't a real aggregate root
+
+        fqn    = "#{domain}::#{ir.hecks_name}"
+        target = namespace_for(entry.fqn.realm, domain, entry.fqn.aggregate)
+
+        target.define_singleton_method(:repository) { dispatcher.registry.repository(domain, ir) }
+        target.define_singleton_method(:count)      { dispatcher.registry.repository(domain, ir).count }
+        target.define_singleton_method(:events)     { dispatcher.events.select { |event| event.aggregate == fqn } }
+
+        target.define_singleton_method(:find) do |id|
+          found = dispatcher.registry.repository(domain, ir).find(id)
+          found && Facade::Handle.new(dispatcher: dispatcher, domain: domain, ir: ir, instance: found)
+        end
+
+        target.define_singleton_method(:all) do
+          dispatcher.registry.repository(domain, ir).all.map do |instance|
+            Facade::Handle.new(dispatcher: dispatcher, domain: domain, ir: ir, instance: instance)
+          end
+        end
+      end
+
+      def install_shortcuts!
+        installer = self
+        current_entries.reject { |entry| entry.fqn.aggregate.nil? }
+                       .group_by { |entry| [entry.fqn.aggregate, entry.fqn.verb] }
+                       .each do |(aggregate, verb), candidates|
+          shortcut_target(aggregate).define_singleton_method(verb) { |**args|
+            installer.send(:dispatch_short, candidates, **args)
+          }
+        end
+      end
+
+      def dispatch_short(candidates, **args)
+        if candidates.length > 1
+          shown = candidates.map { |entry| entry.fqn.to_s }.sort.join(", ")
+          aggregate, verb = candidates.first.fqn.aggregate, candidates.first.fqn.verb
+          raise AmbiguousShortRoute, "#{aggregate}.#{verb} is ambiguous — choose one of: #{shown}"
+        end
+
+        entry = candidates.fetch(0)
+        entry.command? ? router.dispatch(entry.fqn.to_s, **args) : router.query(entry.fqn.to_s, **args)
+      end
+
+      def shortcut_target(aggregate)
+        constant = Object.const_get(aggregate, false) if Object.const_defined?(aggregate, false)
+        raise NameError,
+              "cannot install Bluebook shortcut #{aggregate}: it is not a module" if constant && !constant.is_a?(Module)
+
+        constant || Object.const_set(aggregate, Module.new)
+      end
+
+      def namespace_for(realm, domain, aggregate)
+        [realm, domain, aggregate].compact.reduce(Object) do |parent, name|
+          constant = parent.const_get(name, false) if parent.const_defined?(name, false)
+          raise NameError,
+                "cannot install Bluebook route under #{parent}::#{name}: it is not a module" if constant && !constant.is_a?(Module)
+
+          constant || parent.const_set(name, Module.new)
+        end
+      end
+    end
+  end
+end