hecks 5.0.0 → 6.0.0

data/lib/hecks/runtime/outbox/runnable.rb

@@ -0,0 +1,60 @@
+require_relative "../adapter_lookup"
+require_relative "../errors"
+
+module Hecks
+  module Runtime
+    module Outbox
+      # Whether this process can run what a redriven row asks of the outside. A policy's `ask` is
+      # answered by the adapter bound to its port, and a process that booted without that adapter
+      # (a one-shot command that loads no application constants, say) would only turn the row into
+      # a refusal nobody sees. It leaves the row pending for a process that has the adapter, and
+      # says so once. Mixed into {Relay}, which supplies `registry` and `log`.
+      module Runnable
+        private
+
+        # Records that a row was left pending, and warns the first time its reason is seen.
+        #
+        # @return [Boolean] true when the row must not be claimed here
+        def withheld?(row)
+          reason = unrunnable_reason(row) or return false
+
+          @log << { outbox: row.delivery_id, consumer: row.consumer, withheld: true, reason: reason }
+          @withheld_reasons ||= []
+          warn withheld_wording(row, reason) if @withheld_reasons.push(reason).count(reason) == 1
+          true
+        end
+
+        def withheld_wording(row, reason)
+          "[hecks] outbox row #{row.delivery_id} (#{row.consumer} on #{row.event[:name]}) left pending: " \
+            "#{reason}. A process that has the adapter will run it; it stays visible in `outbox.rows`."
+        end
+
+        # @return [String, nil] why the row's ask cannot run in this process, nil when it can
+        def unrunnable_reason(row)
+          target = ask_target(row) or return nil
+
+          adapter_bound?(*target) ? nil : "no adapter bound for #{target.join(".")} in this process"
+        end
+
+        def adapter_bound?(port, operation)
+          AdapterLookup.adapter_class(@registry, port, asked: operation)
+          true
+        rescue WiringError, NameError
+          false
+        end
+
+        # @return [Array(String, String), nil] the port and operation the row's policy asks, nil
+        #   when the row is not an ask
+        def ask_target(row)
+          kind, fqn = row.consumer.split(":", 2)
+          home, name = fqn.split("::", 2)
+          policy = kind == "policy" && @registry.bluebook(home)&.policies&.find { |candidate| candidate.name == name }
+          return nil unless policy&.asks?
+
+          aggregate_and_port, operation = policy.trigger_command.split(".", 2)
+          [aggregate_and_port.split("::").last, operation]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/outbox.rb

@@ -13,13 +13,27 @@ module Hecks
       # pending -> claimed -> delivered | failed
       STATUSES = %w[pending claimed delivered failed].freeze
 
+      # How long a row stays claimed before it counts as stalled: a claim that old was left by a
+      # process that is gone, where a younger one is a reaction running in another process. Ten
+      # minutes is the ceiling a reaction is expected to stay inside.
+      STALLED_AFTER = 600
+
+      # `claimed_for` is the seconds since the row was claimed, read from the store's own clock; nil
+      # when the store does not say.
       Row = Struct.new(:id, :delivery_id, :event_uid, :aggregate, :domain, :kind, :consumer, :event,
-                       :status, :attempts, :error, keyword_init: true) do
+                       :status, :attempts, :error, :claimed_for, keyword_init: true) do
         def pending?   = status == "pending"
         def claimed?   = status == "claimed"
         def delivered? = status == "delivered"
         def failed?    = status == "failed"
 
+        # A claimed row is stalled when its age is unknown or past `STALLED_AFTER`; a younger one is
+        # a reaction still running.
+        def stalled? = claimed? && (claimed_for.nil? || claimed_for >= STALLED_AFTER)
+
+        # @return [Integer, nil] whole seconds since the claim, or nil when the store does not say
+        def claimed_seconds_ago = claimed_for&.round
+
         # Wire shape persisted by adapters; `Outbox.event_from` reverses it.
         def to_h
           { id: id, delivery_id: delivery_id, event_uid: event_uid, aggregate: aggregate, domain: domain,

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

@@ -19,10 +19,16 @@ module Hecks
           payload = event.payload.transform_keys(&:to_sym).merge(extra)
           return payload unless ReactionInvocation.projection_declared?(policy)
 
-          source = row.transform_keys(&:to_sym).merge(emitter_identity(event)).merge(payload)
+          source = emitter_id(event).merge(row.transform_keys(&:to_sym)).merge(emitter_identity(event)).merge(payload)
           projected_args(policy, event, source)
         end
 
+        # The emitting record's whole identity as `:id`, below everything else: a fan-out row
+        # carries its own `id`, and a payload field of that name wins (ADR 0153).
+        def emitter_id(event)
+          event.id.nil? || event.id.to_s.empty? ? {} : { id: event.id }
+        end
+
         def projected_args(policy, event, payload)
           args = ReactionInvocation.resolve_mapping(
             with_spec: policy.with_spec,

data/lib/hecks/runtime/policy_interpreter/fan_out.rb

@@ -1,13 +1,11 @@
-require_relative "../../naming"
 require_relative "../errors"
-require_relative "../query_interpreter"
-require_relative "../refusal_wording"
+require_relative "../row_sweep"
 
 module Hecks
   module Runtime
     class PolicyInterpreter
       # A `for_each` policy: asks a query which rows the event concerns, and fires the trigger
-      # once per row. Mixed into {PolicyInterpreter}.
+      # once per row through the {RowSweep} a bulk run shares. Mixed into {PolicyInterpreter}.
       module FanOut
         private
 
@@ -32,13 +30,15 @@ module Hecks
         # The rows the `for_each` query answers, and the key by which the trigger addresses a row.
         def for_each_rows(policy, event, domain, target)
           query_domain, aggregate_name, query_name = policy.for_each_route(domain)
-          aggregate = resolve_query_aggregate(query_domain, aggregate_name, policy.for_each)
+          aggregate = row_sweep.query_aggregate(query_domain, aggregate_name, verb: policy.for_each)
           # The query reads the event, never the `with:` projection: it asks which rows.
           query_args = for_each_query_args(aggregate.query(query_name), event)
-          rows = QueryInterpreter.new(@registry).call(query_domain, aggregate, query_name, query_args)
-          [rows, addressing_key_for(target, aggregate_name)]
+          rows = row_sweep.rows(query_domain, aggregate, query_name, query_args)
+          [rows, row_sweep.addressing_key_for(target, aggregate_name, label: "for_each's own trigger")]
         end
 
+        def row_sweep = @row_sweep ||= RowSweep.new(@registry)
+
         # The event's own identity is not in its payload, so a query argument named
         # after an identity head of the emitting aggregate is filled from `event.id`.
         # Without it the query silently sees nothing. Never overrides a payload value.
@@ -57,38 +57,11 @@ module Hecks
           query.attributes.select { |attribute| heads.include?(attribute.name.to_s) && !args.key?(attribute.name) }
         end
 
-        # Resolves `target` back to its declared command and asks it how a row of
-        # `aggregate_name` addresses it. Raises rather than guessing when the command is
-        # unresolvable or cannot be addressed: a domain-authoring mistake to surface.
-        def addressing_key_for(target, aggregate_name)
-          target_domain, target_aggregate_name, target_command_name = Naming.split_verb(target)
-          command = @registry.bluebook(target_domain)&.aggregate(target_aggregate_name)&.command(target_command_name)
-          raise UnknownVerb, "for_each's own trigger #{target.inspect} does not resolve to a declared command" unless command
-
-          key = command.addressing_key_for(aggregate_name)
-          return key if key
-
-          raise ArgumentError,
-                "#{target} cannot be addressed by a row of #{aggregate_name} — it declares no self-reference to " \
-                "#{aggregate_name} and no reference-typed attribute targeting it"
-        end
-
         def deliver_for_each_row(target, row_record, args, policy, event)
           return depth_refusal(row_record) if @dispatcher.reaction_depth_reached?
 
           # The row key is already merged by `trigger_args`, so a projection can name it.
-          @dispatcher.reenter(target, **reaction_invocation(target, args, policy, event))
-          row_record.merge(delivered: true)
-        rescue *DOMAIN_REFUSALS => e
-          row_record.merge(delivered: false, reason: e.message)
-        end
-
-        def resolve_query_aggregate(domain, aggregate_name, verb)
-          bluebook = @registry.bluebook(domain) ||
-                     raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_domain", domain: domain, verb: verb))
-          bluebook.aggregate(aggregate_name) ||
-            raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_aggregate",
-                                                          domain: domain, aggregate: aggregate_name))
+          row_sweep.deliver(row_record) { @dispatcher.reenter(target, **reaction_invocation(target, args, policy, event)) }
         end
       end
     end

data/lib/hecks/runtime/policy_interpreter.rb

@@ -99,10 +99,18 @@ module Hecks
         return depth_refusal(record) if @dispatcher.reaction_depth_reached?
 
         args = trigger_args(policy, event)
+        log_cross_domain(policy, target, args)
         @dispatcher.reenter(target, **reaction_invocation(target, args, policy, event))
         record.merge(delivered: true)
       end
 
+      # What an `across` policy hands the other domain, noted before the delivery is attempted.
+      def log_cross_domain(policy, target, args)
+        return unless policy.target_domain
+
+        @registry.cross_domain_log << { policy: policy.name, target_verb: target, payload: args }
+      end
+
       def depth_refusal(record)
         record.merge(delivered: false, reason: "reaction depth #{@dispatcher.max_reaction_depth} reached")
       end

data/lib/hecks/runtime/port_operation_interpreter.rb

@@ -1,5 +1,7 @@
 require_relative "adapter_lookup"
+require_relative "asking"
 require_relative "interpreting"
+require_relative "dispatch_context"
 require_relative "command_interpreter/argument_gate"
 require_relative "event"
 require_relative "value"
@@ -13,7 +15,15 @@ module Hecks
       include Interpreting
       include CommandInterpreter::ArgumentGate
 
-      Context = Struct.new(:domain, :aggregate, :operation, :args, :route, :instance, :result, :invocation)
+      Context = Struct.new(:domain, :aggregate, :operation, :args, :route, :instance, :result, :invocation) do
+        include DispatchContext
+
+        # @return [String] the operation's declared name
+        def operation_hecks_name = operation.hecks_name
+
+        # @return [Object] the identity of the record the route names
+        def route_identity = route.aggregate
+      end
 
       DISPATCH_ORDER = %i[
         refuse_unknown_arguments refuse_absent_arguments normalize_args resolve_references resolve_route emit
@@ -67,8 +77,8 @@ module Hecks
 
       def step_resolve_route(ctx)
         ctx.instance = step(:resolve_route) do
-          @registry.repository(ctx.domain, ctx.aggregate).find(ctx.route.aggregate) ||
-            raise(NotFound, "#{ctx.aggregate.hecks_name} #{ctx.route.aggregate.inspect} does not exist")
+          @registry.repository(ctx.domain, ctx.aggregate).find(ctx.route_identity) ||
+            raise(NotFound, "#{ctx.aggregate_hecks_name} #{ctx.route_identity.inspect} does not exist")
         end
       end
 
@@ -84,14 +94,16 @@ module Hecks
       # needs data that lives on the record, and an event payload carries only arguments.
       # Arguments win over state.
       def ask(ctx)
-        announce(ctx, ctx.operation.answers, ctx.args.merge(spread(adapter_answer(ctx))))
+        operation = ctx.operation
+        announce(ctx, operation.answers, ctx.args.merge(spread(adapter_answer(ctx))))
       rescue StandardError => e
-        announce(ctx, ctx.operation.refuses, ctx.args.merge(refusal: { value: "#{e.class}: #{e.message}" }))
+        announce(ctx, operation.refuses, ctx.args.merge(refusal: { value: "#{e.class}: #{e.message}" }))
       end
 
       def adapter_answer(ctx)
         payload = held_state(ctx).merge(materialise(ctx.args))
-        adapter_for(ctx).public_send(Naming.snake(ctx.operation.hecks_name), **payload)
+        adapter = adapter_for(ctx)
+        Asking.with(@registry) { adapter.public_send(Naming.snake(ctx.operation_hecks_name), **payload) }
       end
 
       # The answer is spread, not nested: a policy re-enters its target with the event
@@ -107,7 +119,7 @@ module Hecks
       # The record, if there is one. A missing record is not an error here: the ask still
       # goes with only its arguments, since `resolve_references` already checked existence.
       def held_state(ctx)
-        ctx.instance ? Value.materialize(ctx.instance.state) : {}
+        ctx.instance ? Value.materialize(ctx.state) : {}
       rescue StandardError
         {}
       end
@@ -115,13 +127,14 @@ module Hecks
       # The port this operation belongs to, found through the aggregate rather than
       # threaded through the call.
       def port_name_for(ctx)
-        owning = ctx.aggregate.ports.find { |port| port.operations.any? { |op| op.equal?(ctx.operation) } }
+        aggregate = ctx.aggregate
+        owning = aggregate.ports.find { |port| port.operations.any? { |op| op.equal?(ctx.operation) } }
         owning&.name or raise WiringError,
-                              "#{ctx.operation.hecks_name} belongs to no port on #{ctx.aggregate.hecks_name}"
+                              "#{ctx.operation_hecks_name} belongs to no port on #{aggregate.hecks_name}"
       end
 
       def adapter_for(ctx)
-        AdapterLookup.call(@registry, port_name_for(ctx), asked: ctx.operation.hecks_name)
+        AdapterLookup.call(@registry, port_name_for(ctx), asked: ctx.operation_hecks_name, aggregate: ctx.aggregate)
       end
 
       # Adapters are handed plain data, never a Value.
@@ -136,7 +149,8 @@ module Hecks
       # Unlike CommandRules::Emission there is no mutated instance to read an id off; the
       # event is stamped with the coerced reference to the owning aggregate (already a plain id).
       def emit(ctx)
-        ctx.operation.emits.map do |event_name|
+        operation = ctx.operation
+        operation.emits.map do |event_name|
           event = event_for(ctx, event_name, ctx.args)
           @registry.event_log << event.emit!
           event
@@ -146,8 +160,8 @@ module Hecks
       def event_for(ctx, event_name, payload)
         Event.new(
           name:        event_name,
-          aggregate:   "#{ctx.domain}::#{ctx.aggregate.hecks_name}",
-          id:          ctx.route.aggregate,
+          aggregate:   "#{ctx.domain}::#{ctx.aggregate_hecks_name}",
+          id:          ctx.route_identity,
           payload:     payload,
           occurred_at: Event.stamp
         )

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

@@ -25,7 +25,7 @@ module Hecks
         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)
+          adapter = AdapterLookup.call(@registry, port.name, asked: asked, aggregate: aggregate)
           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)

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

@@ -0,0 +1,42 @@
+require_relative "../../ports/query/cursor"
+
+module Hecks
+  module Runtime
+    class QueryInterpreter
+      # Answers a cursor query a page at a time (ADR 0130). Mixed into {QueryInterpreter}.
+      module Paging
+        # Answers one page of a cursor query: the rows, and the token of the page after them.
+        #
+        # The query is asked for one row past its page; that row proves a next page exists and is
+        # not answered.
+        #
+        # @param query_name [String] a declared aggregate query that declares `cursor`
+        # @param args [Hash] the query's arguments; `:after` is the position, absent on page one
+        # @return [Hash{Symbol => Object}] `rows` (frozen Hashes) and `after` (a String, nil on the
+        #   last page)
+        # @param page_size [Integer, nil] a page smaller than the query's own `limit`; never larger
+        # @raise [ArgumentError] if the query has no cursor, or `after` is not a token it handed out
+        def page(domain, aggregate, query_name, args, page_size: nil)
+          declared = declared_query(aggregate, query_name)
+          raise ArgumentError, "#{query_name} declares no cursor, so it has no pages" unless declared.cursor
+
+          size = [declared_page_size(declared, normalize_args(aggregate, declared, args)), page_size || Float::INFINITY].min
+          rows, after = Ports::Query::Cursor.split(call(domain, aggregate, query_name, args, widen: size), declared, size)
+          { rows: rows, after: after }
+        end
+
+        private
+
+        # The cursor's position, then offset, then limit. Offset comes before limit, as SQL's
+        # `LIMIT n OFFSET m` and Ports::Query::InMemory do.
+        def paginate(ordered, declared, args)
+          ordered = Ports::Query::Cursor.after(ordered, declared, args) if declared.cursor
+          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
+
+        def declared_page_size(declared, args) = resolve_query_value(declared.limit.value, args).to_i
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+require_relative "../value"
+require_relative "../wasm_plugin"
+
+module Hecks
+  module Runtime
+    class QueryInterpreter
+      # A query a wasm plugin answers: no hecksagon binds it, and one loaded plugin adapter says it
+      # answers it. Mixed into {QueryInterpreter}, beside {OutsideAnswer}, whose argument and
+      # shape checks it shares.
+      module PluginAnswer
+        private
+
+        # The one plugin adapter that answers this query, or nil when none says it does.
+        # Boot has already refused a query two plugins claim.
+        def answering_plugin(domain, aggregate, declared)
+          return nil unless declared.returns
+
+          @registry.plugins_answering("#{domain}::#{aggregate.hecks_name}.#{declared.name}").first
+        end
+
+        # Asks the plugin, with each referenced record handed over as its stored state, and
+        # builds its rows as the value object the query `returns`.
+        #
+        # @return [Array<Hash>] the rows as the returned value object's fields, frozen
+        def answered_by_plugin(domain, aggregate, declared, args, plugin)
+          asked = "#{aggregate.hecks_name}.#{declared.name}"
+          refuse_offered_arguments!(declared, args, asked)
+          question = "#{domain}::#{asked}"
+          answer   = WasmPlugin.ask(plugin, question, plugin_arguments(domain, aggregate, declared, args))
+          Freezer.deep(shaped(aggregate, declared, answer, asked))
+        end
+
+        # The arguments as plain data, a reference replaced by the state of the record it names,
+        # so a plugin reads the record it was asked about without reaching the store.
+        def plugin_arguments(domain, aggregate, declared, args)
+          plain = Value.materialize(args)
+          declared.attributes.select(&:reference?).each_with_object(plain) do |attribute, arguments|
+            name = attribute.name.to_sym
+            next if arguments[name].nil?
+
+            arguments[name] = referenced_state(domain, aggregate, attribute, arguments[name])
+          end
+        end
+
+        def referenced_state(domain, aggregate, attribute, id)
+          target = attribute.target_aggregate || aggregate
+          record = @registry.repository(domain, target).find(id) or
+            raise NotFound, "#{aggregate.hecks_name}.#{attribute.name}: no #{target.hecks_name} #{id.inspect}"
+          Value.materialize(record.to_h)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+module Hecks
+  module Runtime
+    class QueryInterpreter
+      # The form of a declared query a store answers itself: its arguments normalized, the
+      # tenant scope and reference hops applied, as `#call` hands it to the store's native hook.
+      module StoreSpecification
+        # The specification and arguments the store would answer a query with, or nil when an
+        # outside port, a plugin or an entity answers it instead.
+        #
+        # @param domain [String] the domain the aggregate belongs to
+        # @param aggregate [Bluebook::Aggregate] the aggregate declaring the query
+        # @param query_name [String] the query's declared name
+        # @param args [Hash{Symbol => Object}] the query's arguments
+        # @return [Array(QuerySpecification::Common::Options, Hash), nil] the specification and its
+        #   normalized arguments, or nil when the store does not answer the query
+        # @raise [Runtime::UnknownVerb] if `query_name` names no declared query
+        def store_specification(domain, aggregate, query_name, args)
+          return nil if query_name.include?(".")
+
+          declared = declared_query(aggregate, query_name)
+          return nil if aggregate.query_binding(declared.name) || answering_plugin(domain, aggregate, declared)
+
+          args = normalize_args(aggregate, declared, args)
+          declared = TenantScope.apply(declared, args)
+          [ReferenceHop.apply(declared, args, registry: @registry, domain: domain, aggregate: aggregate), args]
+        end
+      end
+    end
+  end
+end
+
+Hecks::Runtime::QueryInterpreter.include(Hecks::Runtime::QueryInterpreter::StoreSpecification)

data/lib/hecks/runtime/query_interpreter.rb

@@ -11,6 +11,9 @@ require_relative "value"
 require_relative "query_interpreter/arguments"
 require_relative "query_interpreter/entity_rows"
 require_relative "query_interpreter/outside_answer"
+require_relative "query_interpreter/paging"
+require_relative "query_interpreter/plugin_answer"
+require_relative "query_interpreter/store_specification"
 
 module Hecks
   module Runtime
@@ -20,6 +23,8 @@ module Hecks
       include Arguments
       include EntityRows
       include OutsideAnswer
+      include PluginAnswer
+      include Paging
 
       attr_reader :registry
 
@@ -35,14 +40,18 @@ module Hecks
       # @raise [Runtime::UnknownVerb] if `query_name` names no declared query
       # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its type
       # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
-      def call(domain, aggregate, query_name, args)
+      def call(domain, aggregate, query_name, args, widen: nil)
         return entity_rows(domain, aggregate, query_name, args) if query_name.include?(".")
 
         declared = declared_query(aggregate, query_name)
         args = normalize_args(aggregate, declared, args)
+        declared = Ports::Query::Cursor::Widened.new(declared, widen) if widen
         port = aggregate.query_binding(declared.name)
         return answered_from_outside(aggregate, declared, args, port) if port
 
+        plugin = answering_plugin(domain, aggregate, declared)
+        return answered_by_plugin(domain, aggregate, declared, args, plugin) if plugin
+
         Freezer.deep(local_answer(domain, aggregate, declared, args))
       end
 
@@ -65,6 +74,9 @@ module Hecks
         port = aggregate.query_binding(declared.name)
         return answered_from_outside(aggregate, declared, args, port) if port
 
+        plugin = answering_plugin(domain, aggregate, declared)
+        return answered_by_plugin(domain, aggregate, declared, args, plugin) if plugin
+
         declared = TenantScope.apply(declared, args)
         reference_interpret(@registry.repository(domain, aggregate).all, declared, args,
                             domain: domain, shape: aggregate)
@@ -116,12 +128,6 @@ module Hecks
         rows_of(paginate(ordered(matched, declared.order_by, declared.null_semantics), declared, args))
       end
 
-      # 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
       # false whatever the comparator; comparing nil directly would answer `ne` true.
       def reference_where_holds?(clause, record, args, domain:, shape:)
@@ -136,8 +142,9 @@ module Hecks
       end
 
       def hop_reference_ids(record, hop)
-        held = record[hop.attribute.name]
-        (hop.attribute.list? ? Array(held) : [held]).compact
+        attribute = hop.attribute
+        held = record[attribute.name]
+        (attribute.list? ? Array(held) : [held]).compact
       end
 
       def hop_holds?(inner, reference_id, args, domain, hop)

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

@@ -1,5 +1,6 @@
 require_relative "../../naming"
 require_relative "../errors"
+require_relative "../refusal_wording"
 
 module Hecks
   module Runtime
@@ -14,7 +15,10 @@ module Hecks
           domain, aggregate_name, command_path = Naming.split_verb(verb)
           raise UnknownVerb, "reaction target #{verb.inspect} is not a qualified command" unless command_path
 
-          aggregate = registry.bluebook(domain)&.aggregate(aggregate_name)
+          bluebook = registry.bluebook(domain)
+          raise UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_domain", domain: domain, verb: verb) unless bluebook
+
+          aggregate = bluebook.aggregate(aggregate_name)
           raise UnknownVerb, "reaction target #{verb.inspect} does not resolve to an aggregate" unless aggregate
 
           *entity_names, command_name = command_path.split(".")
@@ -58,8 +62,9 @@ module Hecks
         end
 
         def aggregate_aliases(target)
-          aliases = [:aggregate, Naming.reference_key(target.aggregate.name)]
-          aliases.unshift(target.command.addressing_key_for(target.aggregate.name)) if target.entities.empty?
+          aggregate = target.aggregate
+          aliases = [:aggregate, Naming.reference_key(aggregate.name)]
+          aliases.unshift(target.command.addressing_key_for(aggregate.name)) if target.entities.empty?
           aliases.compact.uniq
         end
 
@@ -80,7 +85,8 @@ module Hecks
         end
 
         def same_aggregate?(target, source_aggregate)
-          source_aggregate == (source_aggregate.include?("::") ? target.aggregate.hecks_fqn : target.aggregate.hecks_name)
+          aggregate = target.aggregate
+          source_aggregate == (source_aggregate.include?("::") ? aggregate.hecks_fqn : aggregate.hecks_name)
         end
       end
     end

data/lib/hecks/runtime/reaction_invocation.rb

@@ -14,7 +14,10 @@ module Hecks
       # :facts, not :values — Struct.new already defines #values (every
       # member's own value, in order); naming this field :values would
       # silently shadow that with the single Hash it actually holds.
-      Scope = Struct.new(:name, :facts, keyword_init: true)
+      Scope = Struct.new(:name, :facts, keyword_init: true) do
+        # @return [String] the names of the facts this scope makes visible, sorted, comma-joined
+        def visible_fields = facts.keys.sort.join(", ")
+      end
 
       module_function
 
@@ -73,7 +76,7 @@ module Hecks
       def refuse_invisible!(source, scopes, label)
         names = scopes.map(&:name).join(" then ")
         # Names every visible option so a caller isn't left guessing at fields.
-        offered = scopes.map { |scope| "#{scope.name}: #{scope.facts.keys.sort.join(", ")}" }.join("; ")
+        offered = scopes.map { |scope| "#{scope.name}: #{scope.visible_fields}" }.join("; ")
         raise UnknownArgument,
               "#{label}'s with: reads :#{source}, which is not visible in #{names} (visible — #{offered})"
       end

data/lib/hecks/runtime/read_model_interpreter/head_ordering.rb

@@ -40,7 +40,7 @@ module Hecks
 
         def reference_fields(aggregate, target)
           aggregate.attributes
-                   .select { |attribute| attribute.reference? && attribute.type.target_name == target.to_s }
+                   .select { |attribute| attribute.reference? && attribute.target_name == target.to_s }
                    .map(&:name)
         end
       end