hecks 1.0.2 → 1.1.0

data/lib/hecks/runtime/outbox.rb

@@ -0,0 +1,365 @@
+require "json"
+require "securerandom"
+require "time"
+require_relative "event"
+require_relative "../naming"
+
+module Hecks
+  module Runtime
+    # THE TRANSACTIONAL OUTBOX — the durable hand-off between "a command
+    # committed" and "everything that was owed because it committed":
+    # the policies that react to its events, the process managers that
+    # advance on them, and (through a policy whose trigger is an
+    # outbound port operation) the external effects those reactions
+    # cause. `future-features.md` item 8, built.
+    #
+    # THE SHAPE. One row per (event, consumer). A consumer is a named
+    # policy or process manager that would react to the event — resolved
+    # at ENQUEUE time from the registry (`Fanout`), so the outbox records
+    # WHO was owed what, not just that an event happened. Rows move
+    # `pending → claimed → delivered | failed`:
+    #
+    #   pending    written in the SAME adapter transaction as the
+    #              aggregate save (`Interpreting#run_dispatch_order`
+    #              wraps `save` + `emit` + enqueue in `repository.
+    #              transaction`), so a row exists iff the state change
+    #              it reacts to committed — never one without the other.
+    #   claimed    the relay is about to run this consumer. Set BEFORE
+    #              the reaction (a policy's `reenter`, a saga leg's
+    #              dispatch, an adapter call) runs.
+    #   delivered  the consumer ran to completion — including the
+    #              "ran and was refused" case, which is a delivered
+    #              outcome the reaction log already records; the outbox
+    #              tracks delivery, not the domain's answer.
+    #   failed     the consumer raised a defect (non-refusal error).
+    #
+    # DELIVERY IS INLINE BY DEFAULT — the dispatcher drains the rows it
+    # just wrote, in the same call, in the order C10.2 fixes (per event
+    # in `emits` order: that event's policy rows, then its saga rows —
+    # the emitting domain's own policies before other domains'). Nothing about the
+    # happy path is deferred or asynchronous; a caller still sees every
+    # reaction settled when `dispatch` returns. What changes is the
+    # crash window: a process that dies between commit and reaction
+    # used to lose the reaction silently. Now the row survives, and
+    # `Relay#redrive!` — run at boot by `Loader.run_boot_gates!` —
+    # finds it.
+    #
+    # WHAT REDRIVE DOES, AND DELIBERATELY DOESN'T. A `pending` row is
+    # REDRIVEN: its consumer provably never started (claiming is the
+    # first thing delivery does), so running it now is exactly-once by
+    # construction. A `claimed` row is NOT auto-redriven: the consumer
+    # started and the crash hid its outcome — the same reasoning
+    # `saga_pending_dispatch.rb` gives (a stalled transfer is a better
+    # defect than a double-credited one). It is surfaced loudly
+    # (`warn`, and a `stalled: true` entry in `Relay#log`) and left for
+    # `Relay#redrive!(claimed: true)` — an explicit operator decision,
+    # never a boot-time default. `delivery_id` (event uid + consumer) is
+    # UNIQUE per store, so a re-enqueue of the same fact to the same
+    # consumer is a no-op rather than a second row.
+    #
+    # WHICH ADAPTERS. Memory (in-process rows — visible to specs,
+    # gone with the process, exactly like everything else Memory holds),
+    # Sqlite and Postgres (a `hecks_outbox` table in the aggregate's own
+    # database — the only way the enqueue can share the save's
+    # transaction). An adapter without the contract (`outbox_enqueue`/
+    # `outbox_claim`/`outbox_settle`/`outbox_rows`) gets today's
+    # behaviour unchanged — reactions run directly, nothing durable —
+    # and `Registry::Verification#warn_undurable_outbox!` says so at
+    # boot when the domain declares anything that would have needed it.
+    module Outbox
+      STATUSES = %w[pending claimed delivered failed].freeze
+
+      Row = Struct.new(:id, :delivery_id, :event_uid, :aggregate, :domain, :kind, :consumer, :event,
+                       :status, :attempts, :error, keyword_init: true) do
+        def pending?   = status == "pending"
+        def claimed?   = status == "claimed"
+        def delivered? = status == "delivered"
+        def failed?    = status == "failed"
+
+        # Wire-shaped — what an adapter persists. `event` is the event's
+        # own `to_h` plus correlation; `Row.event_from` reverses it.
+        def to_h
+          { id: id, delivery_id: delivery_id, event_uid: event_uid, aggregate: aggregate, domain: domain,
+            kind: kind, consumer: consumer, event: event, status: status, attempts: attempts, error: error }
+        end
+
+        def to_s = "#{consumer} ← #{event[:name]}(#{event[:aggregate]}##{event[:id]}) [#{status}]"
+        def inspect = "#<Outbox::Row #{self}>"
+      end
+
+      module_function
+
+      def serialize_event(event)
+        event.to_h.merge(correlation: event.correlation)
+      end
+
+      # THE EMITTING DOMAIN'S OWN BLUEBOOK FIRST, then the rest in load
+      # order (C10.2) — the one policy ordering both `PolicyInterpreter#
+      # policies_for` and `Fanout.policies` read.
+      def bluebooks_home_first(registry, domain)
+        home, others = registry.bluebooks.each_value.partition { |bluebook| bluebook.name == domain }
+        home + others
+      end
+
+      def event_from(hash)
+        hash = hash.transform_keys(&:to_sym)
+        Event.new(
+          name:        hash[:name],
+          aggregate:   hash[:aggregate],
+          id:          hash[:id],
+          payload:     deep_symbolize(hash[:payload] || {}),
+          occurred_at: hash[:occurred_at],
+          correlation: hash[:correlation]
+        ).emit!
+      end
+
+      def deep_symbolize(value)
+        case value
+        when Hash  then value.to_h { |k, v| [k.to_sym, deep_symbolize(v)] }
+        when Array then value.map { |element| deep_symbolize(element) }
+        else value
+        end
+      end
+
+      # WHO IS OWED WHAT — the same selection `PolicyInterpreter#policies_for`
+      # and `SagaInterpreter#advance` make at delivery time, made once at
+      # enqueue time so the row names its consumer. Policy rows first,
+      # then saga rows, event order preserved within each: exactly the
+      # order `Dispatcher#dispatch` always ran them in.
+      module Fanout
+        module_function
+
+        # ONE UID PER EVENT for this enqueue — the Event struct is
+        # frozen after `emit!`, so the uid lives on the rows rather than
+        # on it (and stays off `Event#to_h`, whose shape the golden and
+        # parity specs pin). Policy and saga rows for the same event
+        # share it, which is what makes `delivery_id` mean "this fact,
+        # this consumer".
+        # ROW ORDER IS DELIVERY ORDER (C10.2): per event, in `emits`
+        # order — that event's policy rows, then its saga rows.
+        def rows_for(registry, events, domain)
+          uids = events.to_h { |event| [event, SecureRandom.uuid] }
+          events.flat_map do |event|
+            policies(registry, event, domain, uids[event]) + sagas(registry, event, domain, uids[event])
+          end
+        end
+
+        def policies(registry, event, domain, uid)
+          emitting = Naming.demodulise(event.aggregate)
+          Outbox.bluebooks_home_first(registry, domain).flat_map do |bluebook|
+            bluebook.policies.filter_map do |policy|
+              next unless policy.event_name == event.name
+              next unless policy.event_qualifier.nil? || policy.event_qualifier == emitting
+
+              consumer = "policy:#{bluebook.name}::#{policy.name}"
+              Row.new(delivery_id: "#{uid}/#{consumer}", event_uid: uid, domain: domain,
+                      kind: kind_for(registry, policy, bluebook.name), consumer: consumer,
+                      event: Outbox.serialize_event(event), status: "pending", attempts: 0)
+            end
+          end
+        end
+
+        def sagas(registry, event, domain, uid)
+          bluebook = registry.bluebook(domain)
+          return [] unless bluebook
+
+          bluebook.process_managers.select { |process_manager| listens?(process_manager, event) }.map do |process_manager|
+            consumer = "saga:#{bluebook.name}::#{process_manager.name}"
+            Row.new(delivery_id: "#{uid}/#{consumer}", event_uid: uid, domain: domain, kind: "reaction",
+                    consumer: consumer, event: Outbox.serialize_event(event), status: "pending", attempts: 0)
+          end
+        end
+
+        def listens?(process_manager, event)
+          process_manager.starts_on == event.name || process_manager.ends_on == event.name ||
+            !process_manager.handler_for(event.name).nil?
+        end
+
+        # An "effect" is a reaction whose trigger is an outbound port
+        # operation — the row is the durable record that an external
+        # call was owed, claimed right before the adapter is asked and
+        # settled right after. Everything else is a plain "reaction".
+        def kind_for(registry, policy, home_domain)
+          target = "#{policy.target_domain || home_domain}::#{policy.trigger_command}"
+          parsed = Naming.split_verb(target)
+          return "reaction" unless parsed
+
+          target_domain, aggregate_name, path = parsed
+          head, rest = path.to_s.split(".", 2)
+          return "reaction" unless rest
+
+          aggregate = registry.bluebook(target_domain)&.aggregate(aggregate_name)
+          port = aggregate&.port(head)
+          port&.operation(rest)&.outbound? ? "effect" : "reaction"
+        end
+      end
+
+      # THE RELAY — one per `Dispatcher`. Enqueues into a repository's
+      # store, drains rows inline, and redrives what a previous process
+      # left behind.
+      class Relay
+        attr_reader :registry, :log
+
+        # NOT `saga_log`/`reaction_log` — those are ported byte-for-byte
+        # by the Rust kernel (`spec/rust_conformance_spec.rb`); this is
+        # an additive, Ruby-only log, the same rule `saga_dispatch_log`
+        # and `policy_dispatch_log` already follow.
+        def initialize(registry)
+          @registry = registry
+          @log      = []
+        end
+
+        # A Dispatcher hands over the interpreters a consumer runs
+        # through (`Dispatcher#initialize`). Until then this relay can
+        # enqueue (that needs only the registry) but not deliver — and
+        # nothing can dispatch without a dispatcher, so nothing asks it
+        # to. The registry holds ONE relay for its lifetime; a second
+        # dispatcher fronting the same registry re-attaches, which is
+        # fine because both dispatchers share every log and store.
+        def attach(policies:, sagas:)
+          @policies = policies
+          @sagas    = sagas
+          self
+        end
+
+        def attached? = !@policies.nil?
+
+        # Called INSIDE the save transaction by `Interpreting` for the
+        # command/entity paths, and outside one by `Dispatcher` for port
+        # operations (which save nothing, so there is no transaction to
+        # share). Returns the rows as stored (ids assigned), or nil when
+        # the repository has no outbox — the dispatcher then reacts
+        # directly, exactly as before.
+        def enqueue(repository, events, domain)
+          return nil unless repository.outbox?
+          return [] if events.empty?
+
+          rows = Fanout.rows_for(@registry, events, domain)
+          rows.each { |row| row.aggregate = repository.aggregate.storage_name }
+          repository.outbox_enqueue(rows)
+        end
+
+        # Drain the rows a dispatch just committed. `rows` nil means "no
+        # outbox here" — react directly, the pre-outbox path.
+        def deliver(rows, events, domain, repository)
+          if rows.nil?
+            # PER EVENT, in `emits` order — its policies, then its sagas
+            # (C10.2, docs/semantics/bluebook-semantics.md); the same
+            # order `Fanout.rows_for` lays the outbox rows in.
+            events.each do |event|
+              @policies.react(event, domain)
+              @sagas.advance(event, domain)
+            end
+            return
+          end
+
+          rows.each { |row| deliver_row(row, repository) }
+        end
+
+        # One row: claim, run its consumer, settle. A claim that fails
+        # means another relay (or this one, re-entrantly) already has it.
+        def deliver_row(row, repository)
+          return false unless repository.outbox_claim(row.id)
+
+          row.status = "claimed"
+          begin
+            run_consumer(row)
+            repository.outbox_settle(row.id, status: "delivered")
+            row.status = "delivered"
+            true
+          rescue StandardError => e
+            # A DOMAIN_REFUSAL never reaches here — PolicyInterpreter and
+            # SagaInterpreter both rescue it as a recorded, undelivered
+            # reaction. Anything that does reach here is a defect in the
+            # relay's own path (a consumer that no longer exists, an
+            # adapter that raised outside the interpreters' own rescue).
+            repository.outbox_settle(row.id, status: "failed", error: "#{e.class}: #{e.message}")
+            row.status = "failed"
+            row.error  = "#{e.class}: #{e.message}"
+            @log << { outbox: row.delivery_id, consumer: row.consumer, delivered: false, defect: true,
+                      reason: row.error }
+            false
+          end
+        end
+
+        # Every row in every bound store, newest last. `status:` narrows.
+        def rows(status: nil)
+          stores.flat_map { |repository| repository.outbox_rows(status: status) }
+        end
+
+        # BOOT-TIME RECONCILIATION. Redrives `pending` rows (never
+        # claimed — safe by construction); surfaces `claimed` rows and
+        # redrives them ONLY when told to (`claimed: true`).
+        def redrive!(claimed: false)
+          redriven = []
+          stores.each do |repository|
+            repository.outbox_rows(status: "pending").each do |row|
+              redriven << row if deliver_row(row, repository)
+            end
+            repository.outbox_rows(status: "claimed").each do |row|
+              if claimed
+                repository.outbox_settle(row.id, status: "pending")
+                row.status = "pending"
+                redriven << row if deliver_row(row, repository)
+              else
+                warn_stalled(row)
+              end
+            end
+          end
+          redriven
+        end
+
+        private
+
+        def run_consumer(row)
+          raise WiringError, "outbox relay has no dispatcher attached — nothing can run #{row.consumer}" unless attached?
+
+          event = Outbox.event_from(row.event)
+          kind, fqn = row.consumer.split(":", 2)
+          home, name = fqn.split("::", 2)
+          case kind
+          when "policy"
+            policy = @registry.bluebook(home)&.policies&.find { |candidate| candidate.name == name } ||
+                     raise(WiringError, "outbox row #{row.delivery_id} names policy #{fqn}, which no bluebook declares")
+            @policies.react(event, row.domain, only: [policy, home])
+          when "saga"
+            process_manager = @registry.bluebook(home)&.process_managers&.find { |candidate| candidate.name == name } ||
+                              raise(WiringError,
+                                    "outbox row #{row.delivery_id} names process_manager #{fqn}, which no bluebook declares")
+            @sagas.advance(event, row.domain, only: process_manager)
+          else
+            raise WiringError, "outbox row #{row.delivery_id} has an unknown consumer kind #{kind.inspect}"
+          end
+        end
+
+        def warn_stalled(row)
+          warn "[hecks] outbox row #{row.delivery_id} (#{row.consumer} on #{row.event[:name]} for " \
+               "#{row.event[:aggregate]}##{row.event[:id]}) was claimed before the last crash/restart and never " \
+               "settled — its #{row.kind} may or may not have actually run. hecks does not auto-redrive a claimed " \
+               "row (the outcome is unknown, and redelivering it could double the effect); inspect it and " \
+               "redrive by hand with `runtime.outbox.redrive!(claimed: true)` once you know it is safe."
+          @log << { outbox: row.delivery_id, consumer: row.consumer, kind: row.kind, stalled: true,
+                    event: row.event[:name], aggregate: row.event[:aggregate], id: row.event[:id] }
+        end
+
+        # Every repository the registry can resolve, one per (domain,
+        # aggregate), keeping only those with an outbox. Bluebooks, not
+        # hecksagons: a domain with no hecksagon at all is bound to the
+        # default adapter (Memory), which has one. An aggregate a
+        # hecksagon deliberately left unbound raises WiringError from
+        # `repository` and is skipped — the same "forgotten decision"
+        # rule dispatch itself applies, not softened here.
+        def stores
+          @registry.bluebooks.each_value.flat_map do |bluebook|
+            bluebook.aggregates.filter_map do |aggregate|
+              repository = @registry.repository(bluebook.name, aggregate)
+              repository if repository.outbox?
+            rescue WiringError
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/policy_interpreter.rb

@@ -8,6 +8,11 @@ require_relative "../bluebook/expression/evaluator"
 
 module Hecks
   module Runtime
+    # Fires the declared `policy` reactions triggered by one just-emitted
+    # event: scans every loaded bluebook (a policy commonly lives in a
+    # different domain than the event it reacts to), checks each
+    # candidate's `where` guard, and re-enters the dispatcher for each
+    # delivery — recording every outcome on the reaction log.
     class PolicyInterpreter
       attr_reader :registry
 
@@ -23,8 +28,13 @@ module Hecks
       # (one record per matched row) rather than one record ; `Array(...)`
       # is wrong here (it would explode a plain record Hash into its own
       # key/value pairs), so the two shapes are told apart explicitly.
-      def react(event, domain)
-        policies_for(event).each do |policy, home_domain|
+      # `only:` — ONE `[policy, home_domain]` pair, the outbox relay's
+      # way of running exactly the consumer a row names (`Runtime::
+      # Outbox::Relay#run_consumer`) instead of every policy that
+      # matches the event. Selection is otherwise identical.
+      def react(event, domain, only: nil)
+        selected = only ? [only] : policies_for(event, domain)
+        selected.each do |policy, home_domain|
           result = deliver(policy, event, home_domain)
           next if result.nil?
 
@@ -52,10 +62,15 @@ module Hecks
       # OWN domain (not the emitting one) when a trigger or for_each route
       # is bare, and that fallback has to travel with each match now that
       # a single event can surface policies from several different homes.
-      def policies_for(event)
+      #
+      # THE EMITTING DOMAIN'S OWN POLICIES FIRST, in declaration order,
+      # then other bluebooks' in load order (C10.2) — the same order the
+      # outbox lays its rows in (`Outbox::Fanout.policies`) and the Rust
+      # kernel runs (`react_policies`: its own table, then cross-domain).
+      def policies_for(event, domain)
         emitting = Naming.demodulise(event.aggregate)
 
-        @registry.bluebooks.each_value.flat_map do |bluebook|
+        Outbox.bluebooks_home_first(@registry, domain).flat_map do |bluebook|
           matching = bluebook.policies.select do |policy|
             policy.event_name == event.name &&
               (policy.event_qualifier.nil? || policy.event_qualifier == emitting)
@@ -78,7 +93,7 @@ module Hecks
       def where_holds?(policy, event)
         return true if policy.where.to_s.empty?
 
-        Bluebook::Expression::Evaluator.call(policy.where, {}, event.payload.transform_keys(&:to_sym))
+        Bluebook::Expression::Evaluator.call_rule(policy.where_rule, {}, event.payload.transform_keys(&:to_sym))
       end
 
       def deliver(policy, event, domain)
@@ -101,11 +116,11 @@ module Hecks
         args = trigger_args(policy, event)
         @door.reenter(target, **reaction_invocation(target, args, policy, event))
         record.merge(delivered: true)
-      rescue *DOMAIN_REFUSALS => error
+      rescue *DOMAIN_REFUSALS => e
         # The target refused — a fact about the domain, recorded and not
         # fatal to the command that emitted the event.
-        record.merge(delivered: false, reason: error.message)
-      rescue StandardError => error
+        record.merge(delivered: false, reason: e.message)
+      rescue StandardError => e
         # A DEFECT, not a refusal — a NoMethodError in an interpreter, a
         # NameError from a missing constant, a TypeError from a bad
         # assumption : exactly the class of thing DOMAIN_REFUSALS
@@ -133,8 +148,8 @@ module Hecks
         # is never silent, and left exactly where it happened for a human
         # to find — never re-raised, and never swallowed either.
         warn "[hecks] defect in reaction — policy #{policy.name} on #{event.name} " \
-             "firing #{target}: #{error.class}: #{error.message}"
-        record.merge(delivered: false, reason: error.message, defect: true, error_class: error.class.name)
+             "firing #{target}: #{e.class}: #{e.message}"
+        record.merge(delivered: false, reason: e.message, defect: true, error_class: e.class.name)
       end
 
       # THE FAN-OUT — `policy.for_each` names a query ; this runs it
@@ -169,12 +184,12 @@ module Hecks
         Array(rows).map do |row|
           deliver_for_each_row(target, record, trigger_args(policy, event, reference_key => row[:id]), row, policy, event)
         end
-      rescue *DOMAIN_REFUSALS => error
-        record.merge(delivered: false, reason: error.message)
-      rescue StandardError => error
+      rescue *DOMAIN_REFUSALS => e
+        record.merge(delivered: false, reason: e.message)
+      rescue StandardError => e
         warn "[hecks] defect in reaction — policy #{policy.name} on #{event.name} " \
-             "resolving for_each #{policy.for_each}: #{error.class}: #{error.message}"
-        record.merge(delivered: false, reason: error.message, defect: true, error_class: error.class.name)
+             "resolving for_each #{policy.for_each}: #{e.class}: #{e.message}"
+        record.merge(delivered: false, reason: e.message, defect: true, error_class: e.class.name)
       end
 
       # THE EVENT'S OWN IDENTITY IS A FACT TOO, not only its payload. A
@@ -332,8 +347,8 @@ module Hecks
         # result, or a projection could never name the row it acts on.
         @door.reenter(target, **reaction_invocation(target, args, policy, event))
         row_record.merge(delivered: true)
-      rescue *DOMAIN_REFUSALS => error
-        row_record.merge(delivered: false, reason: error.message)
+      rescue *DOMAIN_REFUSALS => e
+        row_record.merge(delivered: false, reason: e.message)
       end
 
       def reaction_invocation(target, args, policy, event)

data/lib/hecks/runtime/query_interpreter.rb

@@ -11,6 +11,14 @@ require_relative "value"
 
 module Hecks
   module Runtime
+    # Answers one declared aggregate or entity query against a
+    # repository: prefers a native adapter hook (Ports::Query.execute)
+    # when the store can answer directly, falling back to interpreting
+    # wheres/order_by/limit/offset over every loaded record itself.
+    # #reference_call/#reference_interpret are a SEPARATE, deliberately
+    # naive re-implementation of the same evaluation, used only as the
+    # fuzzer's oracle to catch divergence between adapters and this
+    # interpreter's own native path.
     class QueryInterpreter
       attr_reader :registry
 
@@ -114,11 +122,11 @@ module Hecks
       # has no concept of a reference at all — it would just read the
       # raw id straight off the record and compare THAT).
       def reference_interpret(records, declared, args, domain:, shape:)
-        matched = records.select { |r|
-          declared.wheres.all? { |w|
+        matched = records.select do |r|
+          declared.wheres.all? do |w|
             reference_where_holds?(w, r, args, domain: domain, shape: shape)
-          }
-        }
+          end
+        end
         ordered = ordered(matched, declared.order_by, declared.null_semantics)
         # OFFSET FIRST, THEN LIMIT — same fix, same reasoning, as
         # #interpret's own rows above.
@@ -157,16 +165,8 @@ module Hecks
 
       def entity_rows(domain, aggregate, dotted, args)
         entity_name, query_name = Naming.split_dotted(dotted)
-        entity = aggregate.entities.find { |piece| piece.hecks_name == entity_name } ||
-                 raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_unknown",
-                                                          aggregate: aggregate.hecks_name, entity: entity_name.inspect))
-        declared = entity.query(query_name) ||
-                   raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_query_missing",
-                                                            entity: entity_name, query: query_name.inspect))
+        entity, declared, list_attr = resolve_entity_query(aggregate, entity_name, query_name)
         declared = TenantScope.apply(declared, args)
-        list_attr = aggregate.attributes.find { |a| a.list? && a.type.to_s == entity_name } ||
-                    raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_holds_no_list",
-                                                             aggregate: aggregate.hecks_name, entity: entity_name))
 
         parent_key = Naming.reference_key(aggregate.hecks_name)
         rows = @registry.repository(domain, aggregate).all.flat_map do |record|
@@ -186,6 +186,25 @@ module Hecks
         declared.limit ? skipped.first(resolve_query_value(declared.limit.value, args).to_i) : skipped
       end
 
+      # THE THREE DECLARATIONS `entity_rows` NEEDS BEFORE IT CAN READ A
+      # SINGLE RECORD — the entity itself, its declared query, and the
+      # list attribute that holds it on the aggregate. Extracted from
+      # `entity_rows` (pure extraction, same lookups, same order, same
+      # UnknownVerb refusals) purely to separate "which declarations does
+      # this dotted name resolve to" from the row-computation that follows.
+      def resolve_entity_query(aggregate, entity_name, query_name)
+        entity = aggregate.entities.find { |piece| piece.hecks_name == entity_name } ||
+                 raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_unknown",
+                                                          aggregate: aggregate.hecks_name, entity: entity_name.inspect))
+        declared = entity.query(query_name) ||
+                   raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_query_missing",
+                                                            entity: entity_name, query: query_name.inspect))
+        list_attr = aggregate.attributes.find { |a| a.list? && a.type.to_s == entity_name } ||
+                    raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_holds_no_list",
+                                                             aggregate: aggregate.hecks_name, entity: entity_name))
+        [entity, declared, list_attr]
+      end
+
       # FieldPath.dig, not a raw `element[clause.field.to_sym]` — an
       # entity sub-list row is a plain hash merged from stored state
       # (mixed string/symbol keys depending on adapter, per `#cell`'s own
@@ -259,7 +278,8 @@ module Hecks
         declared.attributes.each_with_object(args.dup) do |attribute, normalized|
           next unless normalized.key?(attribute.name)
 
-          normalized[attribute.name] = Value.for_attribute(aggregate, attribute, normalized[attribute.name])
+          normalized[attribute.name] = Value.for_attribute(aggregate, attribute, normalized[attribute.name],
+                                                           boundary: false)
         end
       end
 
@@ -277,9 +297,9 @@ module Hecks
       def ordered(records, order_by, null_semantics = nil)
         field = order_by&.field
         Ports::Query::Ordering.apply(records, order_by, null_semantics,
-                                     identity: ->(record) { record.id.to_s }) { |record|
+                                     identity: ->(record) { record.id.to_s }) do |record|
           comparable(QuerySpecification::FieldPath.dig(record, field))
-        }
+        end
       end
     end
   end

data/lib/hecks/runtime/reaction_invocation.rb

@@ -44,35 +44,48 @@ module Hecks
         end
 
         with_spec.to_h do |key, source|
-          value = if !source.is_a?(Symbol)
-                    source
-                  elsif normalized_bindings.key?(source)
-                    normalized_bindings.fetch(source)
-                  else
-                    visible = normalized_scopes.find { |scope| scope.facts.key?(source) }
-                    unless visible
-                      names = normalized_scopes.map(&:name).join(" then ")
-                      # WHAT IS VISIBLE, NAMED. A refusal that only says which name is
-                      # missing sent a modeler guessing field after field
-                      # (`number`, `reference`…) at a fan-out row that is addressed
-                      # by ONE key — `account`, the lowercase aggregate — which
-                      # nothing else in the domain spells out. The names each scope
-                      # actually offers are the whole diagnosis; the refusal now
-                      # lists them, scope by scope.
-                      offered = normalized_scopes.map { |scope| "#{scope.name}: #{scope.facts.keys.sort.join(', ')}" }.join("; ")
-                      raise UnknownArgument,
-                            "#{label}'s with: reads :#{source}, which is not visible in #{names} (visible — #{offered})"
-                    end
-                    visible.facts.fetch(source)
-                  end
-
+          value = resolved_mapping_value(source, normalized_bindings, normalized_scopes, label)
           [key.to_sym, Value.materialize(value)]
         end
       end
 
+      # ONE `with:` SOURCE, RESOLVED — pulled out of resolve_mapping
+      # because it is a pure function of its own arguments (a literal, a
+      # binding, or a name visible in some scope), with no dependency on
+      # anything else resolve_mapping's own to_h block is doing.
+      def resolved_mapping_value(source, bindings, scopes, label)
+        return source unless source.is_a?(Symbol)
+        return bindings.fetch(source) if bindings.key?(source)
+
+        visible = scopes.find { |scope| scope.facts.key?(source) }
+        unless visible
+          names = scopes.map(&:name).join(" then ")
+          # WHAT IS VISIBLE, NAMED. A refusal that only says which name is
+          # missing sent a modeler guessing field after field
+          # (`number`, `reference`…) at a fan-out row that is addressed
+          # by ONE key — `account`, the lowercase aggregate — which
+          # nothing else in the domain spells out. The names each scope
+          # actually offers are the whole diagnosis; the refusal now
+          # lists them, scope by scope.
+          offered = scopes.map { |scope| "#{scope.name}: #{scope.facts.keys.sort.join(', ')}" }.join("; ")
+          raise UnknownArgument,
+                "#{label}'s with: reads :#{source}, which is not visible in #{names} (visible — #{offered})"
+        end
+        visible.facts.fetch(source)
+      end
+      private_class_method :resolved_mapping_value
+
       # A reaction without an explicit projection retains wholesale legacy
       # forwarding. Choosing `with:` opts into the strict envelope: only target
       # command attributes enter `with:`, while identities become `to:`.
+      # `consumed` accumulates across the aggregate-identity and entity-
+      # identity steps below, and refuse_unconsumed! at the end reads the
+      # FINAL list — an ordering dependency threaded through one shared
+      # local. Already leans on private helpers (identity_for,
+      # source_receiver_for, command_facts, refuse_unconsumed!) for every
+      # piece that IS self-contained; what remains is the sequencing
+      # itself, which further splitting would only relocate, not remove.
+      # rubocop:disable-next Metrics/MethodLength
       def build(registry:, verb:, projected:, explicit:, passthrough: [], source_receiver: nil)
         args = projected.transform_keys(&:to_sym)
         unless explicit