hecks 3.4.2 → 3.6.0

data/lib/hecks/bluebook/dsl/attribute_collector.rb

@@ -1,9 +1,13 @@
+require_relative "attribute_collector/identity_resolution"
+
 module Hecks
   module Bluebook
     module DSL
       # Mixin for DSL builders that declare attributes: `attribute`, `list_of`, `one_of`,
       # closed-set synthesis, and `identified_by` resolution.
       module AttributeCollector
+        include IdentityResolution
+
         ListOf = Struct.new(:type)
         # `:values` shadows Struct#values so the accessor returns the flat permitted-value array.
         # rubocop:disable-next Lint/StructNewOverride
@@ -12,6 +16,10 @@ module Hecks
         UNSET = Object.new.freeze
         private_constant :UNSET
 
+        ATTRIBUTE_FIELD_OPTIONS = %i[default optional pattern admits].freeze
+        ATTRIBUTE_OPTIONS = [*ATTRIBUTE_FIELD_OPTIONS, :one_of].freeze
+        private_constant :ATTRIBUTE_FIELD_OPTIONS, :ATTRIBUTE_OPTIONS
+
         # Returns the attributes declared so far, minting the accumulating list on first use.
         #
         # @return [Array<Bluebook::Attribute>] the attributes declared so far, in declaration order
@@ -26,48 +34,26 @@ module Hecks
         # Declares one field on the owning construct; the type is a bare constant (ADR 0025).
         #
         #   attribute :op, String, admits: "Vocabulary::QueryComparator"
-        #
         # `admits:` names an already-declared closed set as qualified text, checked on read.
-        # `one_of:` declares an inline closed set and is only meaningful inside a `value_object`.
+        # `one_of:` declares an inline closed set, meaningful only inside a `value_object`.
         #
-        # @param type [Module, ListOf, OneOf] a bare constant or a `list_of`/`one_of` wrapper
+        # @param name [Symbol] the field's name
+        # @param type [Module, ListOf, OneOf] a bare constant or a wrapper
+        # @param options [Hash] `default:`, `optional:`, `pattern:`, `admits:` or `one_of:`
         # @return [void]
-        # @raise [Malformed] on a duplicate name, a missing or quoted type, a disallowed
-        #   pattern, or `one_of:` outside a `value_object`
-        def attribute_impl(name, type = UNSET, default: nil, optional: false, pattern: nil,
-                           admits: nil, one_of: nil)
+        # @raise [Malformed] on a duplicate name, a missing or quoted type, a disallowed pattern
+        # @raise [ArgumentError] on any other keyword
+        def attribute_impl(name, type = UNSET, **options)
           # The FieldName invariant on Root.Attribute enforces the name.
-
+          opts = attribute_options(options)
           refuse_duplicate_attribute!(name)
-
-          if type.equal?(UNSET)
-            raise Malformed, "#{name} declares no type — attribute :#{name}, SomeType is required, " \
-                             "there is no default"
-          end
-
-          # `list_of("X")` carries quoted text one level down; check it before unwrapping.
-          quoted = type.is_a?(ListOf) ? type.type : type
-          if quoted.is_a?(::String)
-            raise Malformed, "#{name}'s type #{quoted.inspect} is quoted text — give the bare constant " \
-                             "(#{quoted}) instead; a forward reference to a value object declared later " \
-                             "in the same block already resolves without quoting"
-          end
-
-          refuse_unshared_pattern(name, pattern) if pattern
+          refuse_unfit_type!(name, type)
+          refuse_unshared_pattern(name, opts[:pattern]) if opts[:pattern]
 
           type = synthesise_closed_set(name, type) if type.is_a?(OneOf)
-          list = type.is_a?(ListOf)
-          attributes << Attribute.new(
-            name:     name,
-            type:     list ? type.type : type,
-            list:     list,
-            default:  default,
-            optional: optional,
-            pattern:  pattern,
-            admits:   admits
-          )
+          attributes << typed_attribute(name, type, opts.slice(*ATTRIBUTE_FIELD_OPTIONS))
 
-          install_inline_closed_set(name, one_of) if one_of
+          install_inline_closed_set(name, opts[:one_of]) if opts[:one_of]
         end
 
         # Wraps a type so `attribute_impl` records it as list-valued: `attribute :x, list_of(Y)`.
@@ -76,13 +62,6 @@ module Hecks
         # GenericDispatch::BOOTSTRAP_CALLS_FALLBACK covers bootstrap.
         def list_of_impl(type) = ListOf.new(type)
 
-        # `reference_to Account` mints `:account`, no `_id` (ADR 0025). Under shadow-parsing the
-        # suffix is kept so frozen era text reconstructs the name it was minted under.
-        private def default_reference_name(target)
-          suffix = MetaValidator.shadow_parsing? ? "_id" : ""
-          :"#{Naming.snake(target)}#{suffix}"
-        end
-
         # Wraps permitted values so `attribute_impl` synthesises a closed-set value object:
         #
         #   attribute :status, one_of("open", "shut")
@@ -92,6 +71,44 @@ module Hecks
 
         private
 
+        # `reference_to Account` mints `:account`, no `_id` (ADR 0025). Under shadow-parsing the
+        # suffix is kept so frozen era text reconstructs the name it was minted under.
+        def default_reference_name(target)
+          suffix = MetaValidator.shadow_parsing? ? "_id" : ""
+          :"#{Naming.snake(target)}#{suffix}"
+        end
+
+        # The keyword options `attribute` accepts, defaulted; anything else is refused the way a
+        # keyword parameter list would refuse it.
+        def attribute_options(options)
+          unknown = options.keys - ATTRIBUTE_OPTIONS
+          unless unknown.empty?
+            raise ArgumentError, "unknown keyword#{"s" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")}"
+          end
+
+          { default: nil, optional: false, pattern: nil, admits: nil, one_of: nil }.merge(options)
+        end
+
+        def typed_attribute(name, type, field_options)
+          list = type.is_a?(ListOf)
+          Attribute.new(name: name, type: list ? type.type : type, list: list, **field_options)
+        end
+
+        def refuse_unfit_type!(name, type)
+          if type.equal?(UNSET)
+            raise Malformed, "#{name} declares no type — attribute :#{name}, SomeType is required, " \
+                             "there is no default"
+          end
+
+          # `list_of("X")` carries quoted text one level down; check it before unwrapping.
+          quoted = type.is_a?(ListOf) ? type.type : type
+          return unless quoted.is_a?(::String)
+
+          raise Malformed, "#{name}'s type #{quoted.inspect} is quoted text — give the bare constant " \
+                           "(#{quoted}) instead; a forward reference to a value object declared later " \
+                           "in the same block already resolves without quoting"
+        end
+
         def relationship_attribute(target, kind, name, optional: false, list: false)
           refuse_duplicate_attribute!(name)
           attributes << Attribute.new(
@@ -140,82 +157,6 @@ module Hecks
           )
           type
         end
-
-        # Each selected identity head contributes all its scalar leaves in declaration order.
-        def resolve_identity_field!(field, value_objects, context_name)
-          attr = attributes.find { |a| a.name == field }
-
-          # A bare `:id` or `_id`-suffixed name with no matching attribute is the walk-parent/
-          # fallback-identity convention (Instance#materialize_identity! falls back to `:id`).
-          return [field.to_s] if attr.nil? && (field.to_s == "id" || field.to_s.end_with?("_id"))
-
-          raise Malformed, "#{context_name}.identified_by :#{field} names no attribute #{context_name} declares" unless attr
-
-          identity_paths_for_attribute(attr, value_objects, context_name, field.to_s, [])
-        end
-
-        # A named or inline identity mints one structured field, then expands
-        # each scalar leaf beneath it into the existing path-shaped IR.
-        def resolve_identity_type!(type, as, insert_at, value_objects, context_name)
-          target = Naming.demodulise(type.respond_to?(:hecks_name) ? type.hecks_name : type)
-          matches = value_objects.select { |value_object| value_object.hecks_name.to_s == target }
-          raise Malformed, "#{context_name}.identified_by names duplicate value object #{target}" if matches.size > 1
-
-          vo = type.respond_to?(:attributes) ? type : matches.first
-          raise Malformed, "#{context_name}.identified_by names #{target}, which is not a declared value object" unless vo
-          raise Malformed, "#{context_name}.identified_by names #{target}, which declares no attributes" if vo.attributes.empty?
-
-          field = (as || Naming.snake(target)).to_sym
-          if attributes.any? { |attribute| attribute.name == field }
-            raise Malformed,
-                  "#{context_name}.identified_by #{target} mints :#{field}, but that attribute is already declared"
-          end
-
-          # `Attribute.new` directly: `vo` is an anonymous class whose `to_s` would spell
-          # "#<Class:0x...>", so the demodulised `target` text is the type.
-          attributes << Attribute.new(name: field, type: target)
-          # Moved to `insert_at`, the attribute count when `identified_by` was called; resolution
-          # runs at build time, so appending would put the identity field last.
-          attributes.insert(insert_at, attributes.pop)
-          vo.attributes.flat_map do |attribute|
-            identity_paths_for_attribute(attribute, value_objects, context_name,
-                                         "#{field}.#{attribute.name}", [target])
-          end
-        end
-
-        def identity_paths_for_attribute(attribute, value_objects, context_name, path, visited)
-          if attribute.list?
-            raise Malformed,
-                  "#{context_name}'s identity member #{path} is a list — an identity member must be scalar"
-          end
-          if attribute.optional?
-            raise Malformed,
-                  "#{context_name}'s identity member #{path} is optional — an identity must be wholly known"
-          end
-
-          return [path] if attribute.reference?
-
-          nested = value_objects.find { |value_object| value_object.hecks_name.to_s == attribute.type.to_s }
-          return [path] unless nested
-
-          if visited.include?(nested.hecks_name.to_s)
-            cycle = [*visited, nested.hecks_name.to_s].join(" -> ")
-            raise Malformed, "#{context_name}'s identity value objects form a cycle: #{cycle}"
-          end
-
-          # A bare field derives one scalar, so each value object on the way must wrap exactly one
-          # field (ADR 0025); otherwise it would silently mint an unannounced compound key.
-          if nested.attributes.size != 1
-            candidates = nested.attributes.map(&:name).join(", ")
-            raise Malformed,
-                  "#{context_name}.identified_by :#{path} names #{nested.hecks_name}, which has " \
-                  "#{nested.attributes.size} field#{'s' unless nested.attributes.size == 1} (#{candidates})"
-          end
-
-          member = nested.attributes.first
-          identity_paths_for_attribute(member, value_objects, context_name, "#{path}.#{member.name}",
-                                       [*visited, nested.hecks_name.to_s])
-        end
       end
     end
   end

data/lib/hecks/bluebook/dsl/binding_proxy.rb

@@ -25,23 +25,7 @@ module Hecks
           aggregate_ir = Hecks.current_registry.bluebook(domain)&.aggregate(aggregate_name) or
             raise Malformed, "#{@fqn} declares no such aggregate — a port needs one to belong to"
 
-          # ConstShim's resolver is one global for the whole dynamic extent; without
-          # swapping it here, a bare `Pizza` inside `reference_to Pizza` would resolve
-          # to another BindingProxy instead of a plain name.
-          built = ConstShim.with(->(const) { const }) { DomainPortBuilder.build(name, owner: aggregate_name, &block) }
-
-          # A `verb`-shaped port is a plain `Port`, the same struct `Hecks.port`
-          # registers — it belongs to no aggregate IR the way an operations-shaped
-          # `DomainPort` does, so it takes the registry's `add_port` directly.
-          if built.is_a?(Port)
-            Hecks.current_registry.add_port(built)
-            return self
-          end
-
-          built.operations.each do |operation|
-            operation.attributes.select(&:reference?).each { |attribute| attribute.type.declared_in = aggregate_ir }
-          end
-          aggregate_ir.add_port(built)
+          register_port(build_port(name, aggregate_name, block), aggregate_ir)
           self
         end
 
@@ -64,6 +48,27 @@ module Hecks
         def respond_to_missing?(_name, _include_private = false) = true
 
         def to_s = @fqn
+
+        private
+
+        # ConstShim's resolver is one global for the whole dynamic extent; without
+        # swapping it here, a bare `Pizza` inside `reference_to Pizza` would resolve
+        # to another BindingProxy instead of a plain name.
+        def build_port(name, aggregate_name, body)
+          ConstShim.with(->(const) { const }) { DomainPortBuilder.build(name, owner: aggregate_name, &body) }
+        end
+
+        # A `verb`-shaped port is a plain `Port`, the same struct `Hecks.port`
+        # registers — it belongs to no aggregate IR the way an operations-shaped
+        # `DomainPort` does, so it takes the registry's `add_port` directly.
+        def register_port(built, aggregate_ir)
+          return Hecks.current_registry.add_port(built) if built.is_a?(Port)
+
+          built.operations.each do |operation|
+            operation.attributes.select(&:reference?).each { |attribute| attribute.type.declared_in = aggregate_ir }
+          end
+          aggregate_ir.add_port(built)
+        end
       end
 
       # What a Privacy-marking chain resolves to after its first bare segment — each
@@ -80,7 +85,7 @@ module Hecks
           return record_marking(name.delete_prefix("has_"), readable_by) if name.start_with?("has_")
 
           if !args.empty? || !kwargs.empty? || block
-            raise Malformed, "#{@fqn}.#{@path.join('.')}.#{name} — an attribute path chain takes no " \
+            raise Malformed, "#{@fqn}.#{@path.join(".")}.#{name} — an attribute path chain takes no " \
                              "arguments except a terminal has_<category>(readable_by:)"
           end
 
@@ -89,7 +94,7 @@ module Hecks
 
         def respond_to_missing?(_name, _include_private = false) = true
 
-        def to_s = "#{@fqn}.#{@path.join('.')}"
+        def to_s = "#{@fqn}.#{@path.join(".")}"
 
         private
 

data/lib/hecks/bluebook/dsl/bluebook_builder/pending_givens.rb

@@ -0,0 +1,109 @@
+module Hecks
+  module Bluebook
+    module DSL
+      # The chapter-wide half of a bare `given` reference: resolves every reference the
+      # aggregates and entities deferred, once the chapter's files are loaded.
+      class BluebookBuilder
+        # The other half of a chapter-wide `given` reference — resolves every reference
+        # `AggregateBuilder#pending_chapter_given` deferred, once the chapter's files are loaded.
+        #
+        # Mutates each placeholder `Given` in place, since it's already embedded by Ruby
+        # object reference in the referencing preconditions and commands.
+        #
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if a pending reference's own `description` names no
+        #   precondition any aggregate in this chapter declares, is ambiguous across several
+        #   aggregates with no `declared_by:` to disambiguate, or `declared_by:` names an
+        #   aggregate that does not declare it
+        def resolve_pending_chapter_givens!
+          fill_pending(@chapter_pending_givens) { |entry| resolve_pending_chapter_given(entry) }
+        end
+
+        # The entity-scoped analogue of `#resolve_pending_chapter_givens!`, resolved
+        # against `@chapter_entity_named_givens` instead.
+        #
+        # @return [void]
+        # @raise [Bluebook::DSL::Malformed] if a pending reference's own `description` names no
+        #   precondition any piece in this chapter declares, is ambiguous across several pieces
+        #   with no `declared_by:` to disambiguate, or `declared_by:` names a piece that does
+        #   not declare it
+        def resolve_pending_chapter_entity_givens!
+          fill_pending(@chapter_entity_pending_givens) { |entry| resolve_pending_chapter_entity_given(entry) }
+        end
+
+        private
+
+        # Copies each resolved rule onto its placeholder, then empties the queue.
+        def fill_pending(entries)
+          entries.each do |entry|
+            resolved = yield(entry)
+            entry[:placeholder].description = resolved.description
+            entry[:placeholder].canonical   = resolved.canonical
+            entry[:placeholder].predicate   = resolved.predicate
+            entry[:placeholder].ast         = resolved.ast
+          end
+          entries.clear
+        end
+
+        def resolve_pending_chapter_given(entry)
+          candidates = RuleReference.resolve_owner_keyed(@chapter_named_givens, entry[:description])
+          declarer   = entry[:declared_by]
+          return candidates[declarer] || raise(Malformed, undeclared_given_message(entry)) if declarer
+          return candidates.values.first if candidates.size == 1
+
+          raise Malformed, candidates.empty? ? unknown_given_message(entry) : ambiguous_given_message(entry, candidates)
+        end
+
+        def undeclared_given_message(entry)
+          "#{entry[:aggregate]}'s given #{entry[:description].inspect} names no precondition " \
+            "#{entry[:declared_by]} declares in this chapter — #{entry[:declared_by]} " \
+            "either hasn't declared #{entry[:description].inspect}, or declared_by: named the " \
+            "wrong aggregate"
+        end
+
+        def unknown_given_message(entry)
+          "#{entry[:aggregate]}'s given #{entry[:description].inspect} names no precondition " \
+            "any aggregate in this chapter ever declares — declare it once with a block " \
+            "(some aggregate's own given(#{entry[:description].inspect}) { ... })"
+        end
+
+        def ambiguous_given_message(entry, candidates)
+          "#{entry[:aggregate]}'s given #{entry[:description].inspect} is ambiguous in this " \
+            "chapter — #{candidates.keys.join(", ")} each declare a DIFFERENT predicate " \
+            "under this same description; name which one with declared_by: (e.g. " \
+            "given(#{entry[:description].inspect}, declared_by: #{candidates.keys.first}))"
+        end
+
+        def resolve_pending_chapter_entity_given(entry)
+          candidates = RuleReference.resolve_owner_keyed(@chapter_entity_named_givens, entry[:description])
+          declarer   = entry[:declared_by]
+          return candidates[declarer] || raise(Malformed, undeclared_entity_given_message(entry)) if declarer
+          return candidates.values.first if candidates.size == 1
+
+          raise Malformed,
+                candidates.empty? ? unknown_entity_given_message(entry) : ambiguous_entity_given_message(entry, candidates)
+        end
+
+        def undeclared_entity_given_message(entry)
+          "#{entry[:entity]}'s given #{entry[:description].inspect} names no precondition " \
+            "#{entry[:declared_by]} declares in this chapter — #{entry[:declared_by]} " \
+            "either hasn't declared #{entry[:description].inspect}, or declared_by: named the " \
+            "wrong piece"
+        end
+
+        def unknown_entity_given_message(entry)
+          "#{entry[:entity]}'s given #{entry[:description].inspect} names no precondition " \
+            "any piece in this chapter ever declares — declare it once with a block " \
+            "(some piece's own given(#{entry[:description].inspect}) { ... })"
+        end
+
+        def ambiguous_entity_given_message(entry, candidates)
+          "#{entry[:entity]}'s given #{entry[:description].inspect} is ambiguous across the " \
+            "chapter's own pieces — #{candidates.keys.join(", ")} each declare a DIFFERENT " \
+            "predicate under this same description; name which one with declared_by: (e.g. " \
+            "given(#{entry[:description].inspect}, declared_by: #{candidates.keys.first.inspect}))"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/correlation_keys.rb

@@ -0,0 +1,105 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class BluebookBuilder
+        module Validation
+          # Checks that a process manager's `correlates_by` lands on a scalar field of the commands
+          # that emit the events it reacts to.
+          module CorrelationKeys
+            private
+
+            # `correlates_by` must land on a scalar: the dotted path is walked against each
+            # command that emits an event the process manager reacts to. A command lacking the
+            # first segment is skipped, since correlation has fallback tiers
+            # (saga_interpreter/correlation.rb).
+            def validate_correlation_keys!(process_managers, aggregates)
+              process_managers.each do |pm|
+                next unless pm.correlates_by
+
+                reason = correlation_key_violation(pm, aggregates)
+                next unless reason
+
+                raise ProcessManagerBuilder::InvalidProcessManager,
+                      "#{pm.name} correlates_by #{pm.correlates_by.inspect}, but #{reason}"
+              end
+            end
+
+            def correlation_key_violation(process_manager, aggregates)
+              head, *rest = process_manager.correlates_by.to_s.split(".")
+              events = reacted_events(process_manager)
+
+              emitting_commands(events, aggregates).each do |owner, command|
+                attribute = command.attributes.find { |a| a.name == head.to_sym }
+                next unless attribute
+
+                reason = list_or_scalar_violation(owner, attribute, rest)
+                return reason if reason
+              end
+
+              nil
+            end
+
+            def reacted_events(process_manager)
+              ([process_manager.starts_on, process_manager.ends_on] + process_manager.handlers.map(&:event_type))
+                .compact
+                .reject { |event| event == ProcessManager::REFUSED }
+                .map { |event| event.to_s.split("::").last }
+                .uniq
+            end
+
+            def emitting_commands(events, aggregates)
+              aggregates.flat_map do |aggregate|
+                commands = aggregate.commands + aggregate.entities.flat_map(&:commands)
+                commands.select { |command| command.emits.map(&:to_s).intersect?(events) }
+                        .map { |command| [aggregate, command] }
+              end
+            end
+
+            def list_or_scalar_violation(owner, attribute, segments)
+              return list_key_violation(attribute.name) if attribute.list?
+
+              walk_scalar(owner, attribute.type.to_s, segments)
+            end
+
+            def list_key_violation(label)
+              "#{label} is a list — a correlation key must name one instance's own field, " \
+                "not a whole collection"
+            end
+
+            # Walks the remaining dotted segments through nested value objects; nil means the walk
+            # bottomed out on a scalar, otherwise the string says why it cannot.
+            def walk_scalar(owner, type_name, segments)
+              return scalar_end_violation(type_name) if segments.empty?
+
+              if Attribute::PRIMITIVES.include?(type_name)
+                return "#{type_name} is already a scalar — #{segments.join(".")} has nothing left to reach"
+              end
+
+              shape = owner.value_object(type_name)
+              return "#{type_name} is not a value object this domain declares" unless shape
+
+              walk_member(owner, shape, type_name, segments)
+            end
+
+            # The walk's end: a scalar, or a value object that still needs a member named.
+            def scalar_end_violation(type_name)
+              return nil if Attribute::PRIMITIVES.include?(type_name)
+
+              "#{type_name} is a value object, not a scalar — name one of its own fields, " \
+                "e.g. #{type_name.downcase}.value"
+            end
+
+            def walk_member(owner, shape, type_name, segments)
+              segment, *rest = segments
+              attribute = shape.attributes.find { |a| a.name == segment.to_sym }
+              return "#{type_name} has no field #{segment.inspect}" unless attribute
+              return list_key_violation("#{type_name}.#{segment}") if attribute.list?
+
+              walk_scalar(owner, attribute.type.to_s, rest)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/event_shapes.rb

@@ -0,0 +1,126 @@
+module Hecks
+  module Bluebook
+    module DSL
+      class BluebookBuilder
+        module Validation
+          # The commands of a chapter and the events they emit: every command that emits an event
+          # must agree on its shape, and the shapes and identities are looked up by event name.
+          module EventShapes
+            private
+
+            # Every command that emits a given event must agree on its structural shape
+            # (name, type, list, optional); `pattern:`/`admits:`/`default:` may differ (ADR 0025).
+            def validate_event_shapes!(aggregates)
+              event_emitters(aggregates).each do |event_name, pairs|
+                next if pairs.size == 1
+
+                refuse_divergent_event!(event_name, pairs) if divergent_shapes?(pairs, aggregates)
+              end
+            end
+
+            def divergent_shapes?(pairs, aggregates)
+              pairs.map { |(owner, command)| event_shape(command, owner_aggregate(owner, aggregates)) }.uniq.size > 1
+            end
+
+            def refuse_divergent_event!(event_name, pairs)
+              named = pairs.map { |(owner, command)| "#{owner}.#{command.hecks_name}" }.sort
+              raise Malformed,
+                    "#{event_name.inspect} is emitted with different shapes by #{named.join(" and ")} — " \
+                    "an event is one fact, and every command that emits it must declare the same fields"
+            end
+
+            # Yields every command the chapter declares with its owner's name
+            # ("Aggregate.Entity" for entities).
+            def each_command(aggregates)
+              return enum_for(:each_command, aggregates) unless block_given?
+
+              aggregates.each do |aggregate|
+                aggregate.commands.each { |command| yield aggregate.hecks_name, command }
+                aggregate.entities.each do |entity|
+                  entity.commands.each { |command| yield "#{aggregate.hecks_name}.#{entity.hecks_name}", command }
+                end
+              end
+            end
+
+            # Not memoised: a chapter split across files is validated once per file, and a
+            # cached index would miss the commands later files add.
+            def event_emitters(aggregates)
+              each_command(aggregates).with_object(Hash.new { |h, k| h[k] = [] }) do |(owner, command), index|
+                command.emits.each { |event_name| index[event_name] << [owner, command] }
+              end
+            end
+
+            # The comparable shape of a command's attributes, value objects unwrapped.
+            # Structural, not nominal: aggregates may type a field with differently named
+            # wrapper value objects without disagreeing about the event. `owner` supplies the
+            # `value_object` lookup, since same-named value objects are private to each aggregate.
+            def event_shape(command, owner)
+              command.attributes.map { |a| shape_row(owner, a, []) }.sort
+            end
+
+            def shape_row(owner, attribute, seen)
+              [attribute.name, unwrap_shape(owner, attribute.type.to_s, seen), attribute.list?, attribute.optional?]
+            end
+
+            def unwrap_shape(owner, type_name, seen = [])
+              return type_name if owner.nil?
+              return type_name if Attribute::PRIMITIVES.include?(type_name)
+              # a self-referential value object bottoms out on its own name
+              return type_name if seen.include?(type_name)
+
+              shape = owner.value_object(type_name)
+              return type_name unless shape
+
+              shape.attributes.map { |a| shape_row(owner, a, seen + [type_name]) }.sort
+            end
+
+            # The value objects a command's fields can be
+            # typed with are the aggregate's own (`Entity` carries no
+            # `value_object` lookup), so only the owner string's first segment matters.
+            def owner_aggregate(owner, aggregates)
+              aggregates.find { |a| a.hecks_name == owner.to_s.split(".").first }
+            end
+
+            def event_shape_for(event_name, aggregates)
+              pairs = event_emitters(aggregates).fetch(event_name.to_s, [])
+              return nil if pairs.empty?
+
+              owner_name, command = pairs.first
+              event_shape(command, owner_aggregate(owner_name, aggregates))
+            end
+
+            # An entity's event is stamped with its owning aggregate's identity, so
+            # "Game.Knight" answers Game's heads.
+            def event_identity_heads_for(event_name, aggregates)
+              pairs = event_emitters(aggregates).fetch(event_name.to_s, [])
+              return [] if pairs.empty?
+
+              owner_name, = pairs.first
+              aggregate = owner_aggregate(owner_name, aggregates)
+              aggregate ? identity_heads_through(aggregate, owner_name) : []
+            end
+
+            # An entity's event also carries the piece's own identity: the args a piece
+            # was addressed by are its payload (`Emission#emit`).
+            def identity_heads_through(aggregate, owner_name)
+              entity = piece_named(aggregate, owner_name)
+              aggregate.identity_heads.map(&:to_sym) + (entity ? entity.identity_heads.map(&:to_sym) : [])
+            end
+
+            def piece_named(aggregate, owner_name)
+              owner_name.to_s.split(".").drop(1).reduce(aggregate) do |owner, name|
+                owner&.entities&.find { |e| e.hecks_name == name }
+              end
+            end
+
+            def command_lookup(aggregates)
+              each_command(aggregates).with_object({}) do |(owner, command), index|
+                index["#{owner}.#{command.hecks_name}"] = command
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end