hecks 1.0.2 → 1.2.0

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

data/lib/hecks/runtime/read_model_interpreter.rb

@@ -8,6 +8,13 @@ require_relative "../query_specification/field_path"
 
 module Hecks
   module Runtime
+    # Interprets one declared `read_model`: resolves each of its
+    # `include`d heads (root first, then the rest in dependency order),
+    # matches non-root heads to already-projected rows by reference
+    # field, and applies group_by/count/median reduction where declared.
+    # Prefers a native SQLite escape hatch (#query_read_model) when the
+    # model is simple enough for one; otherwise runs the whole join
+    # in-process against loaded records.
     class ReadModelInterpreter
       def initialize(registry) = @registry = registry
 
@@ -17,6 +24,19 @@ module Hecks
 
       private
 
+      # ROOT-FIRST, THEN THE SQLITE ESCAPE HATCH, THEN THE JOIN LOOP —
+      # each step's own comment names a real, previously-shipped bug the
+      # current ORDER fixes (the reference/TenantScope refusal ordering
+      # above, the root-first head processing below). Splitting this
+      # into smaller methods would scatter that ordering across method
+      # boundaries where a future editor could silently break it, and
+      # would force threading `rootless`/`reference_id`/`eligible`/
+      # `projected`/`rows_by_as` between the pieces as parameters and
+      # return values.
+      # rubocop:disable-next Metrics/AbcSize
+      # rubocop:disable-next Metrics/CyclomaticComplexity
+      # rubocop:disable-next Metrics/MethodLength
+      # rubocop:disable-next Metrics/PerceivedComplexity
       def project(domain, model, args)
         bluebook = @registry.bluebook(domain)
         rootless = model.reference_target.nil?
@@ -30,10 +50,11 @@ module Hecks
         refuse_object_reference(model, args) unless rootless
         reference_id = reference(args.fetch(model.reference_name)) unless rootless
         # Computed off the ORIGINAL model, before TenantScope wraps it — the
-        # "which head do options apply to" question is about what the
+        # "which head(s) do options apply to" question is about what the
         # bluebook author declared, not about the synthetic tenant clause
-        # the wrapper adds underneath.
-        eligible = model.filtered_head_name
+        # the wrapper adds underneath. Plural (ADR 0055) — `on:` lets more
+        # than one many-side head be eligible at once.
+        eligible = model.filtered_head_names
         model = TenantScope.apply(model, args)
         # A ROOTLESS, `group_by`-declared, or `count`/`median`-declared
         # model skips the SQLite native escape hatch entirely (there is
@@ -46,7 +67,10 @@ module Hecks
         # than narrowed.
         unless rootless || model.group_by.any? || model.count? || model.median_field
           repository = @registry.read_repository(domain, bluebook.aggregate(model.reference_target))
-          return repository.query_read_model(domain, model, args, bluebook) if repository.respond_to?(:query_read_model) && repository.adapter.respond_to?(:query_read_model)
+          if repository.respond_to?(:query_read_model) && repository.adapter.respond_to?(:query_read_model)
+            return repository.query_read_model(domain, model, args,
+                                               bluebook)
+          end
         end
 
         # ROOT FIRST, ALWAYS — regardless of `include` order in the
@@ -96,14 +120,14 @@ module Hecks
                      end
                    end
                  end
-          rows = Ports::Query::InMemory.execute(rows, model, args) if head[:as] == eligible
+          rows = Ports::Query::InMemory.execute(rows, model.options_for(head[:as]), args) if eligible.include?(head[:as])
           projected << { aggregate: head[:aggregate], rows: rows }
           rows_by_as[head[:as]] = head[:many] ? rows : rows.first
         end
         # Declared order preserved in the OUTPUT — only the
         # computation above needed reordering, not what a caller sees
         # back.
-        heads = model.aggregate_heads.each_with_object({}) { |head, report| report[head[:as]] = rows_by_as[head[:as]] }
+        heads = model.aggregate_heads.to_h { |head| [head[:as], rows_by_as[head[:as]]] }
         grouped_head = group_by_target(model, bluebook)
         reduced_head = aggregation_target(model, bluebook)
         [heads.each_with_object({}) do |(as, value), out|
@@ -343,7 +367,7 @@ module Hecks
                  .map(&:name)
       end
 
-      def matching(records) = records.select { |record| yield(record) }.sort_by(&:id)
+      def matching(records, &) = records.select(&).sort_by(&:id)
       def row(record) = record.to_h
     end
   end

data/lib/hecks/runtime/reference_hop.rb

@@ -92,7 +92,7 @@ module Hecks
           @wheres = wheres
         end
 
-        def wheres = @wheres
+        attr_reader :wheres
       end
     end
   end

data/lib/hecks/runtime/refusal_wording.rb

@@ -13,99 +13,105 @@ module Hecks
     # every dispatch, the same reason Expression::Evaluator::
     # SIGN_TEST_OPERATORS is hand-typed beside Vocabulary::SignTest.
     module RefusalWording
+      # `Layout/HashAlignment`'s repo-wide `table` style (.rubocop.yml)
+      # would force every template string below onto the SAME column —
+      # matching the widest key — leaving the longer wordings almost no
+      # room to wrap under Layout/LineLength's own 130-column limit.
+      # Disabled for exactly this one hash literal (a single statement, so
+      # disable-next rather than a disable/enable pair).
+      # rubocop:disable-next Layout/HashAlignment
       TEMPLATES = {
         %w[NotFound creating_no_identity]             =>
-                                                         "{command} creates a {aggregate} — pass {identity}:",
+        "{command} creates a {aggregate} — pass {identity}:",
         %w[AlreadyExists creating_duplicate]          =>
-                                                         "{command} creates a {aggregate} that already exists — {identity} {offered}",
+        "{command} creates a {aggregate} that already exists — {identity} {offered}",
         %w[AlreadyExists entity_duplicate]            =>
-                                                         "a {entity} already exists on {aggregate} — {identity} {offered}",
+        "a {entity} already exists on {aggregate} — {identity} {offered}",
         %w[NotFound acting_no_identity]               =>
-                                                         "{command} acts on an existing {aggregate} — pass {identity}:",
+        "{command} acts on an existing {aggregate} — pass {identity}:",
         %w[NotFound record_missing]                   =>
-                                                         "no {aggregate} with {identity} {offered}",
+        "no {aggregate} with {identity} {offered}",
         %w[NotFound entity_parent_no_identity]        =>
-                                                         "{command} acts on a {aggregate}'s {entity} — pass {identity}:",
+        "{command} acts on a {aggregate}'s {entity} — pass {identity}:",
         %w[UnknownVerb entity_unknown]                =>
-                                                         "{aggregate} has no entity {entity}",
+        "{aggregate} has no entity {entity}",
         %w[NotFound entity_element_no_identity]       =>
-                                                         "{command} acts on one {entity} — pass {identity}:",
+        "{command} acts on one {entity} — pass {identity}:",
         %w[NotFound entity_element_missing]           =>
-                                                         "no {entity} with {identity} {wants} on {aggregate} {parent_id}",
+        "no {entity} with {identity} {wants} on {aggregate} {parent_id}",
         %w[NotFound reference_target_missing]         =>
-                                                         "no {target} with {heads} {key}",
+        "no {target} with {heads} {key}",
         %w[NotFound read_model_reference_missing]     =>
-                                                         "no {aggregate} with reference {offered}",
+        "no {aggregate} with reference {offered}",
         %w[TypeMismatch read_model_object_reference]  =>
-                                                         "{query} refused — a reference is an id, and {field} arrived as an object",
+        "{query} refused — a reference is an id, and {field} arrived as an object",
         %w[UnknownVerb no_query]                      =>
-                                                         "{aggregate} has no query {query}",
+        "{aggregate} has no query {query}",
         %w[UnknownVerb entity_query_missing]          =>
-                                                         "{entity} has no query {query}",
+        "{entity} has no query {query}",
         %w[UnknownVerb entity_holds_no_list]          =>
-                                                         "{aggregate} holds no list of {entity}",
+        "{aggregate} holds no list of {entity}",
         %w[UnknownVerb entity_no_command]             =>
-                                                         "{entity} has no command {command}",
+        "{entity} has no command {command}",
         %w[UnknownVerb aggregate_no_command]          =>
-                                                         "{aggregate} has no command {command}",
+        "{aggregate} has no command {command}",
         %w[UnknownVerb port_no_operation]             =>
-                                                         "{port} has no operation {operation}",
+        "{port} has no operation {operation}",
         %w[UnknownVerb no_domain]                     =>
-                                                         "no domain {domain} loaded (verb {verb})",
+        "no domain {domain} loaded (verb {verb})",
         %w[UnknownVerb no_read_model]                 =>
-                                                         "{domain} has no read model {query}",
+        "{domain} has no read model {query}",
         %w[UnknownVerb not_fully_qualified]           =>
-                                                         "{verb} is not a fully-qualified verb (Domain::Aggregate.Command)",
+        "{verb} is not a fully-qualified verb (Domain::Aggregate.Command)",
         %w[UnknownVerb no_aggregate]                  =>
-                                                         "{domain} has no aggregate {aggregate}",
+        "{domain} has no aggregate {aggregate}",
         %w[LifecycleRefused transition_blocked]       =>
-                                                         "{command} refused — {field} is {current}, and {command} moves it only from {allowed}",
+        "{command} refused — {field} is {current}, and {command} moves it only from {allowed}",
         %w[TypeMismatch value_object_shape]           =>
-                                                         "{name} is a {type} — pass its fields as an object, not {offered}",
+        "{name} is a {type} — pass its fields as an object, not {offered}",
         %w[TypeMismatch reference_as_object]          =>
-                                                         "{command} refused — a reference is an id, and {attribute} arrived as an object{known_by}",
+        "{command} refused — a reference is an id, and {attribute} arrived as an object{known_by}",
         %w[TypeMismatch multi_field_scalar]           =>
-                                                         "{type} has multiple fields and cannot stand in for a scalar",
+        "{type} has multiple fields and cannot stand in for a scalar",
         %w[TypeMismatch composite_identity]           =>
-                                                         "{type} is a composite identity — an identity must have exactly one field",
+        "{type} is a composite identity — an identity must have exactly one field",
         %w[TypeMismatch numeric_field]                =>
-                                                         "{type}.{field} expects {expected}, got {offered}",
+        "{type}.{field} expects {expected}, got {offered}",
         %w[TypeMismatch non_finite_field]             =>
-                                                         "{type}.{field} must be a finite number, got {offered}",
+        "{type}.{field} must be a finite number, got {offered}",
+        %w[TypeMismatch integer_range]                =>
+        "{type}.{field} must fit in a 64-bit integer, got {offered}",
         %w[TypeMismatch pattern_mismatch]             =>
-                                                         "{type}.{field} must match {pattern}, got {offered}",
+        "{type}.{field} must match {pattern}, got {offered}",
         %w[TypeMismatch arithmetic_amount]            =>
-                                                         "{op} of {target} needs an Integer, got {offered}",
+        "{op} of {target} needs an Integer, got {offered}",
         %w[TypeMismatch arithmetic_current]           =>
-                                                         "{op} of {target} needs an Integer {target}, got {offered}",
+        "{op} of {target} needs an Integer {target}, got {offered}",
         %w[TypeMismatch arithmetic_shared_field]      =>
-                                                         "{op} of {target} needs a value object with one shared Integer field",
+        "{op} of {target} needs a value object with one shared Integer field",
         %w[UnknownArgument unknown_args]              =>
-                                                         "{command} does not declare {unknown} — it takes {declared}",
+        "{command} does not declare {unknown} — it takes {declared}",
         %w[AbsentArgument absent_args]                =>
-                                                         "{command} was not given {absent} — it takes {declared}",
+        "{command} was not given {absent} — it takes {declared}",
         %w[InvariantViolation closed_set_member]      =>
-                                                         "{type} admits {admitted} — got {offered}",
+        "{type} admits {admitted} — got {offered}",
         %w[InvariantViolation value_object_invariant] =>
-                                                         "{name} invariant violated — {description} (given {offered})",
+        "{name} invariant violated — {description} (given {offered})",
         %w[InvariantViolation admits_declared_set]    =>
-                                                         "{name} admits {admits} — {admitted} — got {offered}",
+        "{name} admits {admits} — {admitted} — got {offered}",
         %w[InvariantViolation undeclared_set]         =>
-                                                         "{name} admits {admits}, which this chapter does not declare — a closed set is named " \
-                                                         "Aggregate::SetName, and it must be one the bluebook actually holds",
+        "{name} admits {admits}, which this chapter does not declare — a closed set is named Aggregate::SetName, and it must " \
+        "be one the bluebook actually holds",
         %w[Unauthorized tenant_required]              =>
-                                                         "{query} declares authorize with tenant: {field} — pass {field}: to name which " \
-                                                         "{field} this ask is scoped to",
+        "{query} declares authorize with tenant: {field} — pass {field}: to name which {field} this ask is scoped to",
         %w[Unauthorized role_mismatch]                =>
-                                                         "{command} refused — role: {role}, and the caller stated {caller_role}",
+        "{command} refused — role: {role}, and the caller stated {caller_role}",
         %w[AttributeAbsent absent_read]               =>
-                                                         "{aggregate} {field} is absent on this record — declared, not optional, and " \
-                                                         "added since it was written. Backfill it in a translation (backfill :{field}, " \
-                                                         "default: ...), or declare it optional: true",
+        "{aggregate} {field} is absent on this record — declared, not optional, and added since it was written. Backfill it " \
+        "in a translation (backfill :{field}, default: ...), or declare it optional: true",
         %w[ProjectionAbsent absent_read]              =>
-                                                         "{aggregate} {field} is not yet projected on this record — declared via " \
-                                                         "projects :{field}, but no rebuild sweep has populated it. Run the sweep, " \
-                                                         "or read {reference}.{remote_field} directly if this rule cannot wait"
+        "{aggregate} {field} is not yet projected on this record — declared via projects :{field}, but no rebuild sweep has " \
+        "populated it. Run the sweep, or read {reference}.{remote_field} directly if this rule cannot wait"
       }.freeze
 
       module_function

data/lib/hecks/runtime/registry/saga_persistence.rb

@@ -42,7 +42,9 @@ module Hecks
         # why reusing that one would deadlock.
         def saga_persistence(domain)
           key = domain.to_s
-          @saga_persistence[key] || @saga_persistence_mutex.synchronize { @saga_persistence[key] ||= resolve_saga_persistence(key) }
+          @saga_persistence[key] || @saga_persistence_mutex.synchronize do
+            @saga_persistence[key] ||= resolve_saga_persistence(key)
+          end
         end
 
         # WALKS EVERY LOADED DOMAIN, repopulating `saga_instances` from

data/lib/hecks/runtime/registry/verification.rb

@@ -45,6 +45,7 @@ module Hecks
             end
 
             warn_undurable_sagas!(hexagon)
+            warn_undurable_outbox!(hexagon)
           end
           self
         end
@@ -61,10 +62,10 @@ module Hecks
           )
           adapter_class(name)
           self
-        rescue WiringError => error
+        rescue WiringError => e
           raise WiringError,
                 "the default persistence adapter (#{name}) is not usable, so an " \
-                "aggregate with no bind could not be given one: #{error.message}"
+                "aggregate with no bind could not be given one: #{e.message}"
         end
 
         def check_verb(bind)
@@ -227,6 +228,42 @@ module Hecks
         # refusing the boot outright would break a choice an author made
         # deliberately. What a deploy needs is for the gap to be loud and
         # undeniable, not for local dev/test to become impossible.
+        # THE OUTBOX'S TWIN OF `warn_undurable_sagas!` — a domain that
+        # declares anything a commit could owe a reaction to (a policy
+        # listening to one of its events, or a process manager) but is
+        # bound to an adapter with no outbox (`AppendOnly#outbox?`) gets
+        # reactions the pre-outbox way: run inline, lost on a crash
+        # between commit and reaction. A warning, not a refusal, for the
+        # reason `warn_undurable_sagas!` gives — and Memory HAS an outbox
+        # (in-process, like everything else it holds), so a dev/test
+        # boot stays quiet; this speaks up for the file/remote adapters
+        # that persist state durably but hand reactions to nothing.
+        def warn_undurable_outbox!(hexagon)
+          bluebook_ir = bluebook(hexagon.domain)
+          return unless bluebook_ir
+          return if bluebook_ir.process_managers.empty? && !any_policy_listens_to?(bluebook_ir)
+
+          anchor = bluebook_ir.aggregates.first or return
+          bind = Ports::Persistence::BindingPolicy.resolve(self, hexagon.domain, anchor)
+          return if adapter_class(bind.adapter) <= Ports::Persistence::RemoteRuntime
+          return if repository(hexagon.domain, anchor).outbox?
+
+          warn "[hecks] #{hexagon.domain} declares policies/process_managers but its persistence adapter " \
+               "(#{bind.adapter}) has no outbox — reactions run inline and a crash between a command's commit " \
+               "and its reactions loses them silently. Bind SqlitePersistence or Postgres for a durable outbox " \
+               "(see Runtime::Outbox), or accept in-process-only reactions on purpose."
+        rescue WiringError
+          nil
+        end
+
+        def any_policy_listens_to?(bluebook_ir)
+          emitted = bluebook_ir.aggregates.flat_map do |aggregate|
+            aggregate.commands.flat_map(&:emits) +
+              aggregate.ports.flat_map { |port| port.operations.flat_map { |op| [*op.emits, op.answers, op.refuses] } }
+          end.compact.map(&:to_s)
+          @bluebooks.each_value.any? { |candidate| candidate.policies.any? { |policy| emitted.include?(policy.event_name.to_s) } }
+        end
+
         def warn_undurable_sagas!(hexagon)
           bluebook_ir = bluebook(hexagon.domain)
           return unless bluebook_ir

data/lib/hecks/runtime/registry.rb

@@ -1,5 +1,6 @@
 require_relative "registry/verification"
 require_relative "registry/saga_persistence"
+require_relative "outbox"
 
 module Hecks
   module Runtime
@@ -87,8 +88,16 @@ module Hecks
         # reason).
         @saga_persistence = {}
         @saga_persistence_mutex = Mutex.new
+        @outbox = Outbox::Relay.new(self)
       end
 
+      # THE OUTBOX RELAY — one per registry, for its whole life (built
+      # here, never swapped, so no thread ever sees a different one).
+      # It can enqueue from the moment the registry exists; a Dispatcher
+      # attaches the interpreters that let it deliver. See
+      # `Runtime::Outbox`.
+      attr_reader :outbox
+
       # THE BUILDER STAYS OPEN FOR THE LIFE OF THIS REGISTRY, keyed by chapter
       # name — see the comment on `BluebookBuilder.build`. A chapter split across
       # several files (`language/bluebook/*.bluebook`, all `Hecks.bluebook "Bluebook"`)
@@ -201,6 +210,7 @@ module Hecks
         @saga_instances.clear
         @repositories = {}
         @projection_repositories = {}
+        @outbox.log.clear
         rehydrate_sagas!
         self
       end
@@ -249,13 +259,13 @@ module Hecks
       # authoritative bind" check is what actually catches a genuine
       # double-bind; this merge only concatenates, it does not itself
       # decide which of two binds for the same aggregate wins.
-      def merge_hecksagons(a, b)
+      def merge_hecksagons(base, overlay)
         Bluebook::Hecksagon.new(
-          domain:             a.domain,
-          binds:              a.binds + b.binds,
-          subscriptions:      a.subscriptions + b.subscriptions,
-          framework_members:  a.framework_members + b.framework_members,
-          vendored_bluebooks: a.vendored_bluebooks + b.vendored_bluebooks
+          domain:             base.domain,
+          binds:              base.binds + overlay.binds,
+          subscriptions:      base.subscriptions + overlay.subscriptions,
+          framework_members:  base.framework_members + overlay.framework_members,
+          vendored_bluebooks: base.vendored_bluebooks + overlay.vendored_bluebooks
         )
       end
 
@@ -266,12 +276,12 @@ module Hecks
       # also declares REPLACES that key's whole resolved hash (the same
       # all-or-nothing shape `WorldBuilder#method_missing` already builds
       # each entry as), it does not deep-merge field by field within it.
-      def merge_worlds(a, b)
+      def merge_worlds(base, overlay)
         Bluebook::World.new(
-          domain:   a.domain,
-          realm:    b.realm || a.realm,
-          latest:   b.latest || a.latest,
-          settings: a.settings.merge(b.settings)
+          domain:   base.domain,
+          realm:    overlay.realm || base.realm,
+          latest:   overlay.latest || base.latest,
+          settings: base.settings.merge(overlay.settings)
         )
       end
     end

data/lib/hecks/runtime/remote_dispatcher.rb

@@ -81,7 +81,9 @@ module Hecks
         # Lambda that has no way to represent its lineage history at
         # all.
         adapter_name = Ports::Persistence::BindingPolicy.resolve(@registry, domain, aggregate).adapter
-        return @local.dispatch(verb, saga_correlation: saga_correlation, **args) unless @registry.adapter_class(adapter_name) <= Ports::Persistence::RemoteRuntime
+        unless @registry.adapter_class(adapter_name) <= Ports::Persistence::RemoteRuntime
+          return @local.dispatch(verb, saga_correlation: saga_correlation, **args)
+        end
 
         response = @client.dispatch(verb, args)
 

data/lib/hecks/runtime/routing.rb

@@ -19,74 +19,87 @@ module Hecks
       def envelope(to, entity_depth: 0)
         return nil if to.nil?
 
-        aggregate, entities = if to.is_a?(Hash)
-                                hash = to.transform_keys(&:to_sym)
-                                unknown = hash.keys - %i[aggregate entity entities]
-                                unless unknown.empty?
-                                  raise TypeMismatch, "to: does not recognize #{unknown.sort.join(', ')}"
-                                end
-
-                                [hash[:aggregate], entity_identities(hash)]
-                              else
-                                [to, []]
-                              end
-
-        if aggregate.nil? || aggregate.to_s.empty?
-          raise TypeMismatch, "to: must name the receiving aggregate identity"
-        end
+        aggregate, entities = to.is_a?(Hash) ? parse_envelope_hash(to) : [to, []]
+
+        raise TypeMismatch, "to: must name the receiving aggregate identity" if aggregate.nil? || aggregate.to_s.empty?
         if entities.size != entity_depth
           raise TypeMismatch,
                 "to: for an entity command needs #{entity_depth} entity " \
                 "#{entity_depth == 1 ? 'identity' : 'identities'} after the aggregate — got #{entities.size}"
         end
-        if entities.any? { |identity| identity.nil? || identity.to_s.empty? }
-          raise TypeMismatch, "to: contains a blank entity identity"
+        raise TypeMismatch, "to: contains a blank entity identity" if entities.any? do |identity|
+          identity.nil? || identity.to_s.empty?
         end
 
         Envelope.new(aggregate: aggregate, entities: entities)
       end
 
+      # The Hash-shaped half of `to:` — pulled out of `envelope` because
+      # it is a self-contained parse (raises on an unrecognized key, then
+      # returns the pair) with no dependency on anything `envelope` does
+      # afterward; the validations that follow apply the same way
+      # whichever branch produced `aggregate`/`entities`.
+      def parse_envelope_hash(to)
+        hash = to.transform_keys(&:to_sym)
+        unknown = hash.keys - %i[aggregate entity entities]
+        raise TypeMismatch, "to: does not recognize #{unknown.sort.join(', ')}" unless unknown.empty?
+
+        [hash[:aggregate], entity_identities(hash)]
+      end
+      private_class_method :parse_envelope_hash
+
       # `with:` is deliberately strict. Compatibility-only calls still pass
       # loose keyword arguments through the old addressing gate, but a caller
       # choosing the explicit envelope cannot smuggle receiver identity back
       # into the payload.
       def payload(command, with:, legacy:)
         if with && !legacy.empty?
-          raise TypeMismatch, "dispatch takes command facts in with:, not both with: and loose keyword arguments"
+          raise TypeMismatch,
+                "dispatch takes command facts in with:, not both with: and loose keyword arguments"
         end
 
         return legacy unless with
-        unless with.is_a?(Hash)
-          raise TypeMismatch, "with: must be a hash of command facts"
-        end
+        raise TypeMismatch, "with: must be a hash of command facts" unless with.is_a?(Hash)
 
         offered = with.transform_keys(&:to_sym)
         declared = command.attributes.map { |attribute| attribute.name.to_sym }
+        refuse_unknown_facts!(command, offered, declared)
+        refuse_absent_facts!(command, offered, declared)
+        offered
+      end
+
+      # The two `with:` shape checks `payload` runs in sequence — pulled
+      # out because each is a self-contained "compute a difference, raise
+      # if non-empty" rule with no dependency on the other. Order stays
+      # unknown-before-absent, exactly as inline: `payload` calls them in
+      # that order, so a fact that is both unknown AND leaves something
+      # else absent still raises UnknownArgument first, same as before.
+      def refuse_unknown_facts!(command, offered, declared)
         unknown = (offered.keys - declared).sort
-        unless unknown.empty?
-          reading = declared.empty? ? "none" : declared.join(", ")
-          raise UnknownArgument,
-                RefusalWording.render("UnknownArgument", "unknown_args",
-                                      command: command.hecks_name, unknown: unknown.join(", "),
-                                      declared: reading)
-        end
+        return if unknown.empty?
+
+        reading = declared.empty? ? "none" : declared.join(", ")
+        raise UnknownArgument,
+              RefusalWording.render("UnknownArgument", "unknown_args",
+                                    command: command.hecks_name, unknown: unknown.join(", "),
+                                    declared: reading)
+      end
+      private_class_method :refuse_unknown_facts!
 
+      def refuse_absent_facts!(command, offered, declared)
         absent = command.attributes.reject(&:optional?).map { |attribute| attribute.name.to_sym } - offered.keys
-        unless absent.empty?
-          reading = declared.empty? ? "none" : declared.join(", ")
-          raise AbsentArgument,
-                RefusalWording.render("AbsentArgument", "absent_args",
-                                      command: command.hecks_name, absent: absent.sort.join(", "),
-                                      declared: reading)
-        end
+        return if absent.empty?
 
-        offered
+        reading = declared.empty? ? "none" : declared.join(", ")
+        raise AbsentArgument,
+              RefusalWording.render("AbsentArgument", "absent_args",
+                                    command: command.hecks_name, absent: absent.sort.join(", "),
+                                    declared: reading)
       end
+      private_class_method :refuse_absent_facts!
 
       def entity_identities(hash)
-        if hash.key?(:entities) && hash.key?(:entity)
-          raise TypeMismatch, "to: takes entity: or entities:, not both"
-        end
+        raise TypeMismatch, "to: takes entity: or entities:, not both" if hash.key?(:entities) && hash.key?(:entity)
 
         hash.key?(:entities) ? Array(hash[:entities]) : Array(hash[:entity])
       end