hecks 3.5.0 → 3.7.0

data/lib/hecks/runtime/query_interpreter/arguments.rb

@@ -0,0 +1,51 @@
+require_relative "../needs"
+require_relative "../value"
+
+module Hecks
+  module Runtime
+    class QueryInterpreter
+      # How a query's arguments are filled and coerced before it runs. Mixed into
+      # {QueryInterpreter}.
+      module Arguments
+        private
+
+        # Coerces with `boundary: false`: a query's declared argument types are not a
+        # runtime shape check. The exception is a nil for a required value-object-typed
+        # argument, which must refuse as a command argument does; passing it through
+        # would run an unfiltered query (a Ruby/Rust divergence).
+        #
+        # It does not use `Value::Coercion#nil_argument`, which builds a null value object
+        # from field defaults and only refuses when a field has none. `null_vo_argument!`
+        # refuses like any other wrong-shaped value. Command arguments are untouched.
+        def normalize_args(aggregate, declared, args)
+          args = Needs.fill(declared, args, registry: @registry)
+          declared.attributes.each_with_object(args.dup) do |attribute, normalized|
+            next unless normalized.key?(attribute.name)
+
+            normalized[attribute.name] = coerce_argument(aggregate, attribute, normalized[attribute.name])
+          end
+        end
+
+        def coerce_argument(aggregate, attribute, value)
+          return null_vo_argument!(aggregate, attribute) if checked_vo?(aggregate, attribute, value)
+
+          Value.for_attribute(aggregate, attribute, value, boundary: false)
+        end
+
+        def checked_vo?(aggregate, attribute, value)
+          return false unless value.nil?
+          return false if attribute.optional? || attribute.list? || attribute.reference?
+          return false unless aggregate.respond_to?(:value_object)
+
+          !Value.value_object_for(aggregate, attribute.type).nil?
+        end
+
+        # Refuses a nil for a value-object argument; never absorbs it via field defaults.
+        def null_vo_argument!(aggregate, attribute)
+          value_object = Value.value_object_for(aggregate, attribute.type)
+          Value.build(value_object, Value.fields_for(value_object, attribute.name, nil), aggregate)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/query_interpreter/entity_rows.rb

@@ -0,0 +1,82 @@
+require_relative "../../naming"
+require_relative "../../ports/query/ordering"
+require_relative "../../query_specification/field_path"
+require_relative "../errors"
+require_relative "../needs"
+require_relative "../refusal_wording"
+require_relative "../tenant_scope"
+
+module Hecks
+  module Runtime
+    class QueryInterpreter
+      # An entity's query: reads the elements of the aggregate's list that holds it, with no
+      # native path. Mixed into {QueryInterpreter}.
+      module EntityRows
+        private
+
+        def entity_rows(domain, aggregate, dotted, args)
+          entity_name, query_name = Naming.split_dotted(dotted)
+          entity, declared, list_attr = resolve_entity_query(aggregate, entity_name, query_name)
+          args = Needs.fill(declared, args, registry: @registry)
+          declared = TenantScope.apply(declared, args)
+
+          parent_key = Naming.reference_key(aggregate.hecks_name)
+          rows = element_rows(@registry.repository(domain, aggregate).all, list_attr, declared, args, parent_key)
+          # Entity queries have no native path, so offset must be applied here.
+          paginate(ordered_elements(rows, declared.order_by, declared.null_semantics, parent_key, entity.identity_heads),
+                   declared, args)
+        end
+
+        # The elements the wheres admit, each keyed by the identity of the record holding it.
+        def element_rows(records, list_attr, declared, args, parent_key)
+          records.flat_map do |record|
+            Array(record[list_attr.name])
+              .select { |el| declared.wheres.all? { |w| element_where_holds?(w, el, args) } }
+              .map    { |el| { parent_key => record.id }.merge(el) }
+          end
+        end
+
+        # Resolves a dotted name to the entity, its declared query and the list attribute
+        # holding it, refusing with UnknownVerb when any is missing.
+        def resolve_entity_query(aggregate, entity_name, query_name)
+          entity = aggregate.entities.find { |piece| piece.hecks_name == entity_name } ||
+                   raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_unknown",
+                                                                 aggregate: aggregate.hecks_name, entity: entity_name))
+          declared = entity.query(query_name) ||
+                     raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_query_missing",
+                                                                   entity: entity_name, query: query_name))
+          [entity, declared, entity_list(aggregate, entity_name)]
+        end
+
+        def entity_list(aggregate, entity_name)
+          aggregate.attributes.find { |a| a.list? && a.type.to_s == entity_name } ||
+            raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_holds_no_list",
+                                                          aggregate: aggregate.hecks_name, entity: entity_name))
+        end
+
+        # FieldPath.dig, not `element[clause.field.to_sym]`: a dotted field such as
+        # "price.cents" is never a single key.
+        def element_where_holds?(clause, element, args)
+          holds?(clause, QuerySpecification::FieldPath.dig(element, clause.field), args)
+        end
+
+        # Sub-list rows are symbol-keyed because every adapter decodes through
+        # `Ports::Persistence::StateCodec`.
+        def cell(row, key) = row[key.to_sym]
+
+        # Orders by parent first, then every key of the piece in declaration order: two
+        # entities under different parents can share a sequence, and a composite identity
+        # has no single head (`cell(row, nil)` would raise).
+        def ordered_elements(rows, order_by, null_semantics, parent_key, entity_keys)
+          field = order_by&.field
+          Ports::Query::Ordering.apply(
+            rows, order_by, null_semantics,
+            identity: lambda { |row|
+              [row[parent_key].to_s, *Array(entity_keys).map { |key| comparable(cell(row, key)) }]
+            }
+          ) { |row| comparable(QuerySpecification::FieldPath.dig(row, field)) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/query_interpreter/outside_answer.rb

@@ -0,0 +1,89 @@
+require_relative "../../naming"
+require_relative "../adapter_lookup"
+require_relative "../errors"
+require_relative "../refusal_wording"
+require_relative "../value"
+
+module Hecks
+  module Runtime
+    class QueryInterpreter
+      # A query the hecksagon binds to a port: answered by the adapter behind it, and the answer
+      # checked against the value object the query `returns`. Mixed into {QueryInterpreter}.
+      module OutsideAnswer
+        private
+
+        # Asks the port's adapter the question the hecksagon bound to this query, by the query's
+        # snake-cased name and with its arguments as plain data. Each row of the answer is built as
+        # the value object the query `returns`, so an answer that is not that shape is refused
+        # before it enters the domain. The aggregate's records are never read.
+        #
+        # @return [Array<Hash>] the rows as the returned value object's fields, frozen
+        # @raise [Runtime::WiringError] if no adapter answers the port or the adapter lacks the
+        #   method
+        # @raise [Runtime::TypeMismatch, Runtime::InvariantViolation, Runtime::UnknownArgument,
+        #   Runtime::AbsentArgument] naming the query, if the answer is not its declared shape
+        def answered_from_outside(aggregate, declared, args, port)
+          asked = "#{aggregate.hecks_name}.#{declared.name}"
+          refuse_offered_arguments!(declared, args, asked)
+          adapter = AdapterLookup.call(@registry, port.name, asked: asked)
+          method  = Naming.snake(declared.name)
+          # The real adapter's class is what must answer; a fuzz replay's stand-in refuses instead.
+          klass   = AdapterLookup.adapter_class(@registry, port.name, asked: asked)
+          AdapterLookup.check_answers!(klass, port.name, method, declared, asked: asked)
+
+          answer = adapter.public_send(method, **Value.materialize(args))
+          Freezer.deep(shaped(aggregate, declared, answer, asked))
+        end
+
+        # Refuses arguments the adapter cannot be handed: a required one left out, or one the query
+        # does not declare. The adapter is asked by keyword, so either would otherwise reach it as a
+        # raw ArgumentError.
+        #
+        # @raise [Runtime::AbsentArgument] if a non-optional declared argument is missing
+        # @raise [Runtime::UnknownArgument] if `args` names an argument the query does not declare
+        def refuse_offered_arguments!(declared, args, asked)
+          names   = declared.attributes.map { |attribute| attribute.name.to_sym }
+          offered = args.keys.map(&:to_sym)
+          unknown = (offered - names).sort
+          unless unknown.empty?
+            raise UnknownArgument, RefusalWording.render_site("UnknownArgument", "unknown_args",
+                                                              command: asked, unknown: unknown, declared: names)
+          end
+
+          refuse_absent_offered!(declared, offered, names, asked)
+        end
+
+        def refuse_absent_offered!(declared, offered, names, asked)
+          required = declared.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym }
+          absent   = (required - offered).sort
+          return if absent.empty?
+
+          raise AbsentArgument, RefusalWording.render_site("AbsentArgument", "absent_args",
+                                                           command: asked, absent: absent, declared: names)
+        end
+
+        # Builds the adapter's answer as the declared value object: one row, or a list of rows for
+        # `returns list_of(...)`. A refusal keeps its class and gains the query's name.
+        def shaped(aggregate, declared, answer, asked)
+          value_object = Value.value_object_for(aggregate, declared.returns_name) or
+            raise WiringError, "#{asked} returns #{declared.returns_name.inspect}, which the aggregate " \
+                               "declares no value object for"
+          offered = declared.returns_list? ? answer : [answer]
+          unless offered.is_a?(Array) && offered.all?(Hash)
+            raise TypeMismatch, "#{asked} answered outside the domain, but #{answer.class} is not " \
+                                "#{declared.returns_list? ? "a list of" : "a"} #{value_object.hecks_name} row"
+          end
+
+          offered.map { |row| answered_row(value_object, row, aggregate, declared, asked) }
+        end
+
+        # One row of an outside answer, built and validated as the returned value object.
+        def answered_row(value_object, row, aggregate, declared, asked)
+          Value.build(value_object, row, aggregate).to_h
+        rescue TypeMismatch, InvariantViolation, UnknownArgument, AbsentArgument => e
+          raise e.class, "#{asked} answered outside the domain, but not as its #{declared.returns} — #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/query_interpreter.rb

@@ -1,21 +1,26 @@
 require_relative "../naming"
-require_relative "adapter_lookup"
 require_relative "../ports/query"
 require_relative "../ports/query/ordering"
 require_relative "../query_specification/field_path"
 require_relative "../query_specification/common/comparison"
 require_relative "errors"
-require_relative "needs"
 require_relative "reference_hop"
 require_relative "refusal_wording"
 require_relative "tenant_scope"
 require_relative "value"
+require_relative "query_interpreter/arguments"
+require_relative "query_interpreter/entity_rows"
+require_relative "query_interpreter/outside_answer"
 
 module Hecks
   module Runtime
     # Answers one declared aggregate or entity query against a repository, using a
     # native adapter hook when the store has one and interpreting the query otherwise.
     class QueryInterpreter
+      include Arguments
+      include EntityRows
+      include OutsideAnswer
+
       attr_reader :registry
 
       def initialize(registry)
@@ -35,27 +40,10 @@ module Hecks
 
         declared = declared_query(aggregate, query_name)
         args = normalize_args(aggregate, declared, args)
-        if (port = aggregate.query_binding(declared.name))
-          return answered_from_outside(aggregate, declared, args, port)
-        end
-
-        declared = TenantScope.apply(declared, args)
-        # Applied after TenantScope so its tenant clause rides through as an ordinary
-        # local clause; it is deliberately not propagated into the hop's inner query.
-        declared = ReferenceHop.apply(declared, args, registry: @registry, domain: domain, aggregate: aggregate)
-
-        repository = @registry.repository(domain, aggregate)
-        # `registry:` lets a `none_in_state` where-clause look up its target aggregate.
-        if (native = Ports::Query.execute(repository, declared, args,
-                                          context: { domain: domain, aggregate: aggregate, registry: @registry }))
-          records = native
-          # `id` merges last so an aggregate attribute named `id` cannot clobber the
-          # bare identity (see Instance#to_h). Rows are frozen: a mutated row would
-          # edit nobody's state and disagree with the store.
-          return Freezer.deep(records.map { |record| record.state.merge(id: record.id) })
-        end
+        port = aggregate.query_binding(declared.name)
+        return answered_from_outside(aggregate, declared, args, port) if port
 
-        Freezer.deep(interpret(repository.all, declared, args, domain: domain))
+        Freezer.deep(local_answer(domain, aggregate, declared, args))
       end
 
       # The reference answer: this interpreter's own evaluation, never a native hook.
@@ -84,72 +72,27 @@ module Hecks
 
       private
 
-      # Asks the port's adapter the question the hecksagon bound to this query, by the query's
-      # snake-cased name and with its arguments as plain data. Each row of the answer is built as
-      # the value object the query `returns`, so an answer that is not that shape is refused
-      # before it enters the domain. The aggregate's records are never read.
-      #
-      # @return [Array<Hash>] the rows as the returned value object's fields, frozen
-      # @raise [Runtime::WiringError] if no adapter answers the port or the adapter lacks the method
-      # @raise [Runtime::TypeMismatch, Runtime::InvariantViolation, Runtime::UnknownArgument,
-      #   Runtime::AbsentArgument] naming the query, if the answer is not its declared shape
-      def answered_from_outside(aggregate, declared, args, port)
-        asked = "#{aggregate.hecks_name}.#{declared.name}"
-        refuse_offered_arguments!(declared, args, asked)
-        adapter = AdapterLookup.call(@registry, port.name, asked: asked)
-        method  = Naming.snake(declared.name)
-        # The real adapter's class is what must answer; a fuzz replay's stand-in refuses instead.
-        klass   = AdapterLookup.adapter_class(@registry, port.name, asked: asked)
-        AdapterLookup.check_answers!(klass, port.name, method, declared, asked: asked)
-
-        answer = adapter.public_send(method, **Value.materialize(args))
-        Freezer.deep(shaped(aggregate, declared, answer, asked))
-      end
-
-      # Refuses arguments the adapter cannot be handed: a required one left out, or one the query
-      # does not declare. The adapter is asked by keyword, so either would otherwise reach it as a
-      # raw ArgumentError.
-      #
-      # @raise [Runtime::AbsentArgument] if a non-optional declared argument is missing
-      # @raise [Runtime::UnknownArgument] if `args` names an argument the query does not declare
-      def refuse_offered_arguments!(declared, args, asked)
-        names   = declared.attributes.map { |attribute| attribute.name.to_sym }
-        offered = args.keys.map(&:to_sym)
-        unknown = (offered - names).sort
-        unless unknown.empty?
-          raise UnknownArgument, RefusalWording.render_site("UnknownArgument", "unknown_args",
-                                                            command: asked, unknown: unknown, declared: names)
-        end
-
-        required = declared.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym }
-        absent   = (required - offered).sort
-        return if absent.empty?
-
-        raise AbsentArgument, RefusalWording.render_site("AbsentArgument", "absent_args",
-                                                         command: asked, absent: absent, declared: names)
-      end
+      # The rows of a query answered from the aggregate's own records: the adapter's native hook
+      # when the store has one, this interpreter's evaluation otherwise.
+      def local_answer(domain, aggregate, declared, args)
+        declared = TenantScope.apply(declared, args)
+        # Applied after TenantScope so its tenant clause rides through as an ordinary
+        # local clause; it is deliberately not propagated into the hop's inner query.
+        declared = ReferenceHop.apply(declared, args, registry: @registry, domain: domain, aggregate: aggregate)
 
-      # Builds the adapter's answer as the declared value object: one row, or a list of rows for
-      # `returns list_of(...)`. A refusal keeps its class and gains the query's name.
-      def shaped(aggregate, declared, answer, asked)
-        value_object = Value.value_object_for(aggregate, declared.returns_name) or
-          raise WiringError, "#{asked} returns #{declared.returns_name.inspect}, which the aggregate " \
-                             "declares no value object for"
-        offered = declared.returns_list? ? answer : [answer]
-        unless offered.is_a?(Array) && offered.all?(Hash)
-          raise TypeMismatch, "#{asked} answered outside the domain, but #{answer.class} is not " \
-                              "#{declared.returns_list? ? 'a list of' : 'a'} #{value_object.hecks_name} row"
-        end
+        repository = @registry.repository(domain, aggregate)
+        # `registry:` lets a `none_in_state` where-clause look up its target aggregate.
+        native = Ports::Query.execute(repository, declared, args,
+                                      context: { domain: domain, aggregate: aggregate, registry: @registry })
+        return rows_of(native) if native
 
-        offered.map { |row| answered_row(value_object, row, aggregate, declared, asked) }
+        interpret(repository.all, declared, args, domain: domain)
       end
 
-      # One row of an outside answer, built and validated as the returned value object.
-      def answered_row(value_object, row, aggregate, declared, asked)
-        Value.build(value_object, row, aggregate).to_h
-      rescue TypeMismatch, InvariantViolation, UnknownArgument, AbsentArgument => e
-        raise e.class, "#{asked} answered outside the domain, but not as its #{declared.returns} — #{e.message}"
-      end
+      # `id` merges last so an aggregate attribute named `id` cannot clobber the
+      # bare identity (see Instance#to_h). Rows are frozen by the caller: a mutated row would
+      # edit nobody's state and disagree with the store.
+      def rows_of(records) = records.map { |record| record.state.merge(id: record.id) }
 
       def declared_query(aggregate, query_name)
         aggregate.query(query_name) ||
@@ -159,12 +102,7 @@ module Hecks
 
       def interpret(records, declared, args, domain: nil)
         matched = records.select { |r| declared.wheres.all? { |w| where_holds?(w, r, args, domain: domain) } }
-        ordered = ordered(matched, declared.order_by, declared.null_semantics)
-        # Offset before limit, as SQL's `LIMIT n OFFSET m` and Ports::Query::InMemory do.
-        skipped = declared.offset ? ordered.drop(resolve_query_value(declared.offset.value, args).to_i) : ordered
-        capped  = declared.limit ? skipped.first(resolve_query_value(declared.limit.value, args).to_i) : skipped
-
-        capped.map { |r| r.state.merge(id: r.id) }
+        rows_of(paginate(ordered(matched, declared.order_by, declared.null_semantics), declared, args))
       end
 
       # Twin of `interpret` for reference_call: hop clauses go through
@@ -175,11 +113,13 @@ module Hecks
             reference_where_holds?(w, r, args, domain: domain, shape: shape)
           end
         end
-        ordered = ordered(matched, declared.order_by, declared.null_semantics)
-        skipped = declared.offset ? ordered.drop(resolve_query_value(declared.offset.value, args).to_i) : ordered
-        capped  = declared.limit ? skipped.first(resolve_query_value(declared.limit.value, args).to_i) : skipped
+        rows_of(paginate(ordered(matched, declared.order_by, declared.null_semantics), declared, args))
+      end
 
-        capped.map { |r| r.state.merge(id: r.id) }
+      # Offset before limit, as SQL's `LIMIT n OFFSET m` and Ports::Query::InMemory do.
+      def paginate(ordered, declared, args)
+        skipped = declared.offset ? ordered.drop(resolve_query_value(declared.offset.value, args).to_i) : ordered
+        declared.limit ? skipped.first(resolve_query_value(declared.limit.value, args).to_i) : skipped
       end
 
       # Walks each reference by hand. A nil or dangling reference makes the whole clause
@@ -190,73 +130,21 @@ module Hecks
 
         hop, rest = step
         inner = QuerySpecification::Common::WhereClause.new(field: rest, op: clause.op, value: clause.value)
-        held = record[hop.attribute.name]
-        reference_ids = hop.attribute.list? ? Array(held) : [held]
-
-        reference_ids.compact.any? do |reference_id|
-          target_record = @registry.repository(domain, hop.target).find(reference_id)
-          next false unless target_record
-
-          reference_where_holds?(inner, target_record, args, domain: domain, shape: hop.target)
+        hop_reference_ids(record, hop).any? do |reference_id|
+          hop_holds?(inner, reference_id, args, domain, hop)
         end
       end
 
-      def entity_rows(domain, aggregate, dotted, args)
-        entity_name, query_name = Naming.split_dotted(dotted)
-        entity, declared, list_attr = resolve_entity_query(aggregate, entity_name, query_name)
-        args = Needs.fill(declared, args, registry: @registry)
-        declared = TenantScope.apply(declared, args)
-
-        parent_key = Naming.reference_key(aggregate.hecks_name)
-        rows = @registry.repository(domain, aggregate).all.flat_map do |record|
-          Array(record[list_attr.name])
-            .select { |el| declared.wheres.all? { |w| element_where_holds?(w, el, args) } }
-            .map    { |el| { parent_key => record.id }.merge(el) }
-        end
-
-        ordered = ordered_elements(rows, declared.order_by, declared.null_semantics,
-                                   parent_key, entity.identity_heads)
-        # Entity queries have no native path, so offset must be applied here.
-        skipped = declared.offset ? ordered.drop(resolve_query_value(declared.offset.value, args).to_i) : ordered
-        declared.limit ? skipped.first(resolve_query_value(declared.limit.value, args).to_i) : skipped
-      end
-
-      # Resolves a dotted name to the entity, its declared query and the list attribute
-      # holding it, refusing with UnknownVerb when any is missing.
-      def resolve_entity_query(aggregate, entity_name, query_name)
-        entity = aggregate.entities.find { |piece| piece.hecks_name == entity_name } ||
-                 raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_unknown",
-                                                               aggregate: aggregate.hecks_name, entity: entity_name))
-        declared = entity.query(query_name) ||
-                   raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_query_missing",
-                                                                 entity: entity_name, query: query_name))
-        list_attr = aggregate.attributes.find { |a| a.list? && a.type.to_s == entity_name } ||
-                    raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_holds_no_list",
-                                                                  aggregate: aggregate.hecks_name, entity: entity_name))
-        [entity, declared, list_attr]
-      end
-
-      # FieldPath.dig, not `element[clause.field.to_sym]`: a dotted field such as
-      # "price.cents" is never a single key.
-      def element_where_holds?(clause, element, args)
-        holds?(clause, QuerySpecification::FieldPath.dig(element, clause.field), args)
+      def hop_reference_ids(record, hop)
+        held = record[hop.attribute.name]
+        (hop.attribute.list? ? Array(held) : [held]).compact
       end
 
-      # Sub-list rows are symbol-keyed because every adapter decodes through
-      # `Ports::Persistence::StateCodec`.
-      def cell(row, key) = row[key.to_sym]
+      def hop_holds?(inner, reference_id, args, domain, hop)
+        target_record = @registry.repository(domain, hop.target).find(reference_id)
+        return false unless target_record
 
-      # Orders by parent first, then every key of the piece in declaration order: two
-      # entities under different parents can share a sequence, and a composite identity
-      # has no single head (`cell(row, nil)` would raise).
-      def ordered_elements(rows, order_by, null_semantics, parent_key, entity_keys)
-        field = order_by&.field
-        Ports::Query::Ordering.apply(
-          rows, order_by, null_semantics,
-          identity: lambda { |row|
-            [row[parent_key].to_s, *Array(entity_keys).map { |key| comparable(cell(row, key)) }]
-          }
-        ) { |row| comparable(QuerySpecification::FieldPath.dig(row, field)) }
+        reference_where_holds?(inner, target_record, args, domain: domain, shape: hop.target)
       end
 
       def where_holds?(clause, record, args, domain: nil)
@@ -275,42 +163,6 @@ module Hecks
         value.is_a?(Symbol) ? args[value] : value
       end
 
-      # Coerces with `boundary: false`: a query's declared argument types are not a
-      # runtime shape check. The exception is a nil for a required value-object-typed
-      # argument, which must refuse as a command argument does; passing it through
-      # would run an unfiltered query (a Ruby/Rust divergence).
-      #
-      # It does not use `Value::Coercion#nil_argument`, which builds a null value object
-      # from field defaults and only refuses when a field has none. `null_vo_argument!`
-      # refuses like any other wrong-shaped value. Command arguments are untouched.
-      def normalize_args(aggregate, declared, args)
-        args = Needs.fill(declared, args, registry: @registry)
-        declared.attributes.each_with_object(args.dup) do |attribute, normalized|
-          next unless normalized.key?(attribute.name)
-
-          value = normalized[attribute.name]
-          normalized[attribute.name] = if checked_vo?(aggregate, attribute, value)
-                                         null_vo_argument!(aggregate, attribute)
-                                       else
-                                         Value.for_attribute(aggregate, attribute, value, boundary: false)
-                                       end
-        end
-      end
-
-      def checked_vo?(aggregate, attribute, value)
-        return false unless value.nil?
-        return false if attribute.optional? || attribute.list? || attribute.reference?
-        return false unless aggregate.respond_to?(:value_object)
-
-        !Value.value_object_for(aggregate, attribute.type).nil?
-      end
-
-      # Refuses a nil for a value-object argument; never absorbs it via field defaults.
-      def null_vo_argument!(aggregate, attribute)
-        value_object = Value.value_object_for(aggregate, attribute.type)
-        Value.build(value_object, Value.fields_for(value_object, attribute.name, nil), aggregate)
-      end
-
       def comparable(value) = QuerySpecification::Common::Comparison.comparable(value)
 
       # FieldPath.dig, not `record[field]`: a dotted order_by is one symbol key that

data/lib/hecks/runtime/reaction_invocation/identities.rb

@@ -0,0 +1,92 @@
+require_relative "../../naming"
+require_relative "../errors"
+require_relative "../identity"
+require_relative "../value"
+
+module Hecks
+  module Runtime
+    module ReactionInvocation
+      # Reads the receiver identity a reaction's facts carry, for an aggregate or an entity, and
+      # refuses facts that name neither an identity nor a declared argument. Extended onto
+      # {ReactionInvocation}.
+      module Identities
+        private
+
+        # The aggregate's own identity out of the facts, else the one the event lends.
+        def aggregate_identity_for(verb, target, args, inherited_receiver, consumed)
+          identity, keys = identity_for(target.aggregate, args,
+                                        aliases:     aggregate_aliases(target),
+                                        value_owner: target.aggregate)
+          identity ||= inherited_receiver
+          require_identity!(verb, target.aggregate, identity)
+          consumed.concat(keys)
+          identity
+        end
+
+        def entity_identity(verb, entity, target, args, consumed)
+          identity, keys = identity_for(entity, args,
+                                        aliases:     [Naming.reference_key(entity.hecks_name)],
+                                        value_owner: target.aggregate)
+          require_identity!(verb, entity, identity)
+          consumed.concat(keys)
+          identity
+        end
+
+        def identity_for(construct, args, aliases:, value_owner:)
+          identity = Identity.of(construct, args, value_owner: value_owner)
+          return [identity, construct.identity_heads] if identity
+
+          aliases.each do |key|
+            key = key.to_sym
+            next unless args.key?(key)
+
+            identity = identity_from_alias(construct, args[key], value_owner)
+            return [identity, [key]] if identity
+          end
+
+          return [args[:id].to_s, [:id]] if args.key?(:id) && !args[:id].to_s.empty?
+
+          [nil, []]
+        end
+
+        def identity_from_alias(construct, held, value_owner)
+          materialized = Value.materialize(held)
+          return hash_alias_identity(construct, materialized, value_owner) if materialized.is_a?(Hash)
+
+          materialized.to_s unless blank_identity?(materialized)
+        end
+
+        def hash_alias_identity(construct, materialized, value_owner)
+          keyed = materialized.transform_keys(&:to_sym)
+          nested = Identity.of(construct, keyed, value_owner: value_owner)
+          return nested if nested
+          return nil unless construct.identity_paths.one?
+
+          scalar = Identity.scalar(construct.identity_paths.first, keyed)
+          scalar.to_s unless blank_identity?(scalar)
+        end
+
+        def blank_identity?(value)
+          value.nil? || value.to_s.empty?
+        end
+
+        def require_identity!(verb, construct, identity)
+          return if identity
+
+          raise TypeMismatch,
+                "reaction target #{verb} needs #{construct.hecks_name}'s receiver identity outside command facts"
+        end
+
+        def refuse_unconsumed!(command, args, consumed, passthrough)
+          allowed = consumed.map(&:to_sym) + Array(passthrough).map(&:to_sym)
+          unknown = args.keys - allowed
+          return if unknown.empty?
+
+          raise UnknownArgument,
+                "#{command.hecks_name} reaction projection contains neither receiver identity nor declared command facts: " \
+                "#{unknown.sort.join(", ")}"
+        end
+      end
+    end
+  end
+end