hecks 5.0.0 → 7.0.0

data/lib/hecks/runtime/command_rules/one_of_references.rb

@@ -0,0 +1,44 @@
+require_relative "../errors"
+require_relative "../refusal_wording"
+require_relative "../value"
+require_relative "../../bluebook/one_of_union"
+
+module Hecks
+  module Runtime
+    class CommandRules
+      # Refuses a tagged reference (`reference_to one_of(A, B)`, ADR 0127) whose record does not
+      # exist in the aggregate its `type` names. `admits:` has already refused a type outside the
+      # union, so only the lookup is left here.
+      module OneOfReferences
+        # Checks every tagged reference `construct` holds in settled `state`.
+        #
+        # @param domain [String, Symbol] the domain whose repositories are read
+        # @param construct [Bluebook::Aggregate] the aggregate whose state was settled
+        # @param state [Hash{Symbol => Object}] the record's settled fields
+        # @return [void]
+        # @raise [Runtime::NotFound] if a tagged reference names a record that does not exist
+        def resolve_one_of_references(domain, construct, state)
+          Bluebook::OneOfUnion.attributes(construct).each do |attribute|
+            tagged = Value.materialize_unwrapped(state[attribute.name])
+            next unless tagged.is_a?(Hash)
+
+            validate_tagged_reference(domain, construct, tagged)
+          end
+        end
+
+        private
+
+        # Looks the tagged record up in the repository of the aggregate its `type` names.
+        def validate_tagged_reference(domain, construct, tagged)
+          target = construct.hecks_owner&.aggregate(tagged[:type].to_s)
+          key = tagged[:id].to_s
+          return if target.nil? || key.empty? || @registry.repository(domain, target).find(key)
+
+          raise NotFound,
+                RefusalWording.render_site("NotFound", "reference_target_missing",
+                                           target: target.name, heads: target.identity_heads.join(", "), key: key)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/command_rules/references.rb

@@ -1,7 +1,9 @@
 require_relative "../errors"
+require_relative "../collecting"
 require_relative "../refusal_wording"
 require_relative "../value"
 require_relative "../../rendering"
+require_relative "missing_reference"
 require_relative "tenant_boundary"
 
 module Hecks
@@ -24,7 +26,8 @@ module Hecks
         # Re-checks references, cardinality and tenant agreement against settled state.
         #
         # @raise [Runtime::TypeMismatch] if a required `has_one`/`belongs_to` holds nil
-        # @raise [Runtime::NotFound] if a reference names an identity that does not exist
+        # @raise [Runtime::NotFound] if a reference, or a tagged `one_of` reference, names an
+        #   identity that does not exist
         # @raise [Runtime::Unauthorized] if a referenced record belongs to another tenant
         def resolve_state_references(domain, construct, state)
           boundary = TenantBoundary.new(self, domain, construct, state, tenant_field_for(construct))
@@ -36,6 +39,7 @@ module Hecks
           end
 
           resolve_entity_references(domain, construct, state)
+          resolve_one_of_references(domain, construct, state)
         end
 
         # One reference-typed argument's value, refused unless its target identity exists.
@@ -43,7 +47,7 @@ module Hecks
           return if held.nil?
 
           target = referenced_aggregate(attribute)
-          validate_reference_values(domain, target, held, list: attribute.list?) if target
+          validate_reference_values(domain, target, held, list: attribute.list?, attribute: attribute.name) if target
         end
 
         # One reference-typed attribute of settled state: cardinality, target and tenant.
@@ -55,7 +59,7 @@ module Hecks
           target = referenced_aggregate(attribute)
           return unless target
 
-          validate_reference_values(domain, target, held, list: attribute.list?)
+          validate_reference_values(domain, target, held, list: attribute.list?, attribute: attribute.name)
           enforce_tenant_boundary(boundary, attribute, target, held)
         end
 
@@ -84,28 +88,23 @@ module Hecks
           raise TypeMismatch,
                 "#{construct.hecks_name}.#{attribute.name} is a required " \
                 "#{attribute.relationship} relationship — expected one " \
-                "#{attribute.type.target_name} identity, got nil"
+                "#{attribute.target_name} identity, got nil"
         end
 
-        # Resolves the attribute's target through the chapter IR.
+        # Resolves the attribute's target through the bluebook IR.
         #
         # @raise [Bluebook::DSL::Malformed] if the reference does not know its declaring aggregate
-        def referenced_aggregate(attribute)
-          attribute.type.resolve
-        end
+        def referenced_aggregate(attribute) = attribute.target_aggregate
 
         # Refuses a reference-typed value whose target identity does not exist.
-        def validate_reference_values(domain, target, held, list:)
+        def validate_reference_values(domain, target, held, list:, attribute:)
           values = list ? Array(held) : [held]
           values.each do |value|
             key = reference_key(value)
             next if key.empty?
             next if @registry.repository(domain, target).find(key)
 
-            raise NotFound,
-                  RefusalWording.render_site("NotFound", "reference_target_missing",
-                                             target: target.name, heads: target.identity_heads.join(", "),
-                                             key: key)
+            Collecting.refuse(MissingReference.refusal(target, key, attribute))
           end
         end
 
@@ -156,7 +155,8 @@ module Hecks
         end
 
         def dereferenced_name(attribute)
-          attribute.name.to_s.delete_suffix("_id").to_sym
+          name = attribute.name.to_s
+          name.delete_suffix("_id").to_sym
         end
 
         # The target aggregate and stored record a reference argument names, or nil when it names

data/lib/hecks/runtime/command_rules.rb

@@ -1,5 +1,6 @@
 require_relative "command_rules/admissibility"
 require_relative "command_rules/references"
+require_relative "command_rules/one_of_references"
 require_relative "command_rules/arithmetic"
 require_relative "command_rules/emission"
 require_relative "command_rules/authorization"
@@ -14,6 +15,7 @@ module Hecks
     class CommandRules
       include Admissibility
       include References
+      include OneOfReferences
       include Arithmetic
       include Emission
       include Authorization

data/lib/hecks/runtime/declarations.rb

@@ -0,0 +1,66 @@
+module Hecks
+  module Runtime
+    # **A domain's declarations**, asked of the dispatcher or described domain that holds them.
+    #
+    # A caller holding a dispatcher (or a described domain) asks it for a bluebook, a repository
+    # or the translations, rather than reaching through its registry. The includer answers
+    # `registry`.
+    module Declarations
+      # Every loaded bluebook, by name.
+      #
+      # @return [Hash{String => Bluebook::Declaration}] the loaded bluebooks, keyed by name
+      def bluebooks = registry.bluebooks
+
+      # Exposes one loaded domain's bluebook.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @return [Bluebook::Bluebook, nil] the bluebook, or nil when no such domain is loaded
+      def bluebook(domain) = registry.bluebook(domain)
+
+      # The first bluebook loaded: a one-domain boot's own bluebook.
+      #
+      # @return [Bluebook::Declaration, nil] the first loaded bluebook, or nil when none loaded
+      def first_bluebook = registry.first_bluebook
+
+      # Answers whether a domain was loaded as a bounded bluebook.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @return [Boolean] whether the domain is a bounded bluebook
+      def bounded?(domain) = registry.bounded?(domain)
+
+      # The repository that stores `aggregate`.
+      #
+      # @param domain [String, Symbol] the domain `aggregate` belongs to
+      # @param aggregate [Bluebook::Aggregate] the aggregate
+      # @return [Persistence::AppendOnly] the aggregate's authoritative repository
+      def repository(domain, aggregate) = registry.repository(domain, aggregate)
+
+      # A domain's wiring.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @return [Bluebook::Hecksagon, nil] the wiring, or nil when none is registered
+      def hecksagon(domain) = registry.hecksagon(domain)
+
+      # A domain's world settings.
+      #
+      # @param domain [String, Symbol] the domain name
+      # @return [Bluebook::World, nil] the world, or nil when none is registered
+      def world(domain) = registry.world(domain)
+
+      # Every declared translation between eras.
+      #
+      # @return [Array<Bluebook::Translation>] the loaded translations
+      def translations = registry.translations
+
+      # The privacy markings declared before their aggregate was loaded.
+      #
+      # @return [Array<Hash>] each marking's domain, attribute path, category and readers
+      def pending_privacy_markings = registry.pending_privacy_markings
+
+      # Every saga instance this boot has started.
+      #
+      # @return [Hash] the saga instances, by process manager and then correlation
+      def saga_instances = registry.saga_instances
+    end
+  end
+end

data/lib/hecks/runtime/dependency_planning/analyzer.rb

@@ -61,7 +61,8 @@ module Hecks
         # as a read; the interpreter reseeds it on save.
         def owner_field_names(construct)
           fields = construct.attributes.to_set(&:name)
-          fields << construct.lifecycle.field.to_sym if construct.lifecycle
+          lifecycle = construct.lifecycle
+          fields << lifecycle.field.to_sym if lifecycle
           construct.projected_fields.each { |field| fields << field.name } if construct.respond_to?(:projected_fields)
           fields
         end

data/lib/hecks/runtime/dependency_planning/expression_reads.rb

@@ -13,7 +13,6 @@ module Hecks
         # raises before it is stored, so a failure is never cached. Written from dispatch
         # threads, so every access holds PATHS_LOCK; the cache is cleared when it reaches
         # PATHS_CACHE_LIMIT entries, so distinct texts cannot grow it without bound.
-        # rubocop:disable-next Style/MutableConstant
         PATHS_CACHE = {}
         PATHS_LOCK = Mutex.new
         PATHS_CACHE_LIMIT = 4096
@@ -64,8 +63,9 @@ module Hecks
 
         # The path a lookup reads, unless its root is a name an enclosing block bound.
         def collect_lookup(node, bound_names)
-          root = node.path.to_s.split(".", 2).first
-          bound_names.include?(root) ? [] : [node.path.to_s]
+          path = node.path.to_s
+          root = path.split(".", 2).first
+          bound_names.include?(root) ? [] : [path]
         end
       end
     end

data/lib/hecks/runtime/dependency_planning/mutation_analysis.rb

@@ -16,7 +16,8 @@ module Hecks
               known_writes << attribute.name if deterministic_initial_value?(attribute)
             end
 
-            known_writes << aggregate.lifecycle.field.to_sym if aggregate.lifecycle
+            state_field = aggregate.lifecycle_field
+            known_writes << state_field.to_sym if state_field
           end
 
           def deterministic_initial_value?(attribute)

data/lib/hecks/runtime/dispatch_claim.rb

@@ -0,0 +1,72 @@
+module Hecks
+  module Runtime
+    # The identity of one saga dispatch, and the capability a repository needs to dedupe by it.
+    #
+    # A saga leg stamps each command it dispatches with a key naming the saga instance, the event
+    # that moved it, the leg's trigger and the dispatch's position. A repository that declares
+    # `:dispatch_claims` records the key in the same transaction as the write it guards
+    # (`dispatch_claim`) and answers whether a key was applied (`dispatch_applied?`), so delivering
+    # the same dispatch again changes nothing, whatever the command does.
+    module DispatchClaim
+      CAPABILITY = :dispatch_claims
+
+      module_function
+
+      # @param process_manager [String] the saga's declared name
+      # @param correlation [String] the saga instance's correlation value
+      # @param trigger [String] the event name, or `REFUSED`, that selected the leg
+      # @param event [Runtime::Event] the event that moved the leg
+      # @param index [Integer] the dispatch's position within the leg
+      # @return [String] the key, stable across a crash because it is built from the leg's own event
+      def key(process_manager:, correlation:, trigger:, event:, index:)
+        [process_manager, correlation, trigger, event.name, event.id, event.occurred_at, index].join("/")
+      end
+
+      # @param repository [#capabilities] the repository a command saves through
+      # @return [Boolean] whether it dedupes dispatches by key
+      def supported?(repository) = repository.capabilities.include?(CAPABILITY)
+
+      # What an interpreter does with a dispatch key: read it before any step, claim it inside the
+      # save's transaction. Mixed into {Interpreting}; the context carries `dispatch_key`.
+      module Claiming
+        private
+
+        # The steps from `save` onward, run only if this delivery wins the dispatch's claim; a
+        # delivery that lost it applies nothing and answers with no events.
+        def run_transactional_steps(steps, ctx)
+          unless dispatch_claimed?(ctx)
+            ctx.result = []
+            return
+          end
+
+          steps.each { |name| send(:"step_#{name}", ctx) }
+          enqueue_outbox(ctx)
+        end
+
+        # Whether the dispatch may go on: it carries no key, its repository dedupes none, or the
+        # key was new and is now claimed in this transaction. False means another delivery of the
+        # same dispatch got there first, so nothing is applied.
+        def dispatch_claimed?(ctx)
+          return true unless keyed_dispatch?(ctx)
+
+          ctx.repository.dispatch_claim(ctx.dispatch_key)
+        end
+
+        # Whether a saga dispatch with this key was already applied, read before any step runs so a
+        # guard the first delivery changed cannot refuse the second.
+        def dispatch_applied?(ctx)
+          keyed_dispatch?(ctx) && ctx.repository.dispatch_applied?(ctx.dispatch_key)
+        end
+
+        # What a command answers when its dispatch was already applied: no record, no events, and
+        # nothing for the reaction layer to do.
+        def already_applied(ctx) = [nil, [], ctx.plan, nil, []]
+
+        def keyed_dispatch?(ctx)
+          ctx.respond_to?(:dispatch_key) && ctx.dispatch_key && !ctx.dry_run && ctx.repository &&
+            DispatchClaim.supported?(ctx.repository)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/dispatch_context.rb

@@ -0,0 +1,41 @@
+module Hecks
+  module Runtime
+    # What a dispatch step asks its context for, answered from the record, command and
+    # aggregate the context holds. Mixed into each interpreter's `Context` struct, which
+    # supplies the readers (`instance`, `command`, `aggregate`, `route`, ...) these read.
+    module DispatchContext
+      # @return [Hash{Symbol => Object}] the record's held state
+      def state = instance.state
+
+      # @return [Object] the record's identity
+      def instance_id = instance.id
+
+      # @return [Integer, nil] the version the record was read at, nil when never stored
+      def instance_version = instance.version
+
+      # @return [Symbol] what the repository answered the save with (`:stale`, `:conflicted`, ...)
+      def outcome_status = persistence_outcome.status
+
+      # @return [String] the aggregate's declared name
+      def aggregate_hecks_name = aggregate.hecks_name
+
+      # @return [String] the command's declared name
+      def command_hecks_name = command.hecks_name
+
+      # @return [Array] the command's ensures clauses
+      def command_ensures = command.ensures
+
+      # @return [Array] the command's mutations, in declaration order
+      def command_mutations = command.mutations
+
+      # @return [Object] the state the admitted transition moves to
+      def transition_target = transition.target
+
+      # @return [Object] what the repository can do (CAS, locking, atomic put)
+      def capabilities = repository.capabilities
+
+      # @return [Object, nil] the aggregate identity the route names, nil without a route
+      def routed_identity = route&.aggregate
+    end
+  end
+end

data/lib/hecks/runtime/dispatcher/planning.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Runtime
+    class Dispatcher
+      # What a command would write and announce, listed without writing or announcing it. Runs the
+      # in-memory pipeline `dry_run?` runs; the save and emit seams report to DryRunPlan.
+      module Planning
+        # Lists what a command would write and announce, without writing or announcing it.
+        #
+        # Runs the same in-memory pipeline as `dry_run?`, with the save and emit seams reporting
+        # instead of acting, so every command gets its plan from one place.
+        #
+        # @param verb [String] the fully qualified aggregate command verb
+        # @param args [Hash{Symbol => Object}] the facts as flat keywords
+        # @return [Array<String>] one `would write` or `would emit` line per effect, in order
+        # @raise [StandardError] any refusal the real dispatch would raise
+        def plan_flat(verb, **args)
+          DryRunPlan.collect { dry_run_call(flat_call(verb, args)) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/dispatcher/queries.rb

@@ -29,6 +29,23 @@ module Hecks
           @queries.call(domain, aggregate, query_name, args)
         end
 
+        # Answers one page of a cursor query: its rows, and the `after` that asks for the next page.
+        #
+        # @param verb [String] `"Domain::Aggregate.Query"` of a query that declares `cursor`
+        # @param after [String, nil] the position the previous page answered; nil asks page one
+        # @param page_size [Integer, nil] a page smaller than the query's own `limit`; never larger
+        # @param args [Hash{Symbol => Object}] the query's declared arguments
+        # @return [Hash{Symbol => Object}] `rows`, one Hash per record, and `after`, the next
+        #   position or nil when no row follows
+        # @raise [ArgumentError] if the query has no cursor, or `after` is not one it handed out
+        # @raise [Runtime::UnknownVerb] if the verb is malformed or names something undeclared
+        def query_page(verb, after: nil, page_size: nil, **args)
+          domain, aggregate_name, query_name = parse(verb)
+          aggregate = resolve_aggregate(domain, aggregate_name, verb)
+
+          @queries.page(domain, aggregate, query_name, after ? args.merge(after: after) : args, page_size: page_size)
+        end
+
         # Answers an aggregate or entity query through the reference interpreter alone.
         #
         # Never answered by the bound adapter's native hook; the fuzzer's query oracle diffs it

data/lib/hecks/runtime/dispatcher/routing.rb

@@ -2,6 +2,7 @@ require_relative "../errors"
 require_relative "../refusal_wording"
 require_relative "../invocation"
 require_relative "../../naming"
+require_relative "value_routing"
 
 module Hecks
   module Runtime
@@ -9,9 +10,11 @@ module Hecks
       # Finds what a verb names and runs it through the interpreter that owns it. Mixed into
       # {Dispatcher}, which holds the interpreters and the registry these read.
       module Routing
+        include ValueRouting
+
         # One dispatch request as the caller spelled it: the verb, its receiver and facts, and
         # the saga correlation to stamp on emitted events.
-        Call = Struct.new(:verb, :to, :with, :saga_correlation, :flat, keyword_init: true)
+        Call = Struct.new(:verb, :to, :with, :saga_correlation, :dispatch_key, :flat, keyword_init: true)
 
         private
 
@@ -57,32 +60,57 @@ module Hecks
 
         def route_aggregate(call, domain, aggregate, aggregate_name, command_name)
           command = command_of(aggregate, aggregate_name, command_name)
+          handler = value_handler(domain, aggregate, command, call)
+          return route_port(call, domain, aggregate, handler) if handler
+
           invocation = Invocation.from_call(call.verb, to: call.to, with: call.with, flat: call.flat) { command }
-          @commands.call(domain, aggregate, command, invocation, call.saga_correlation)
+          @commands.call(domain, aggregate, command, invocation, call.saga_correlation, dispatch_key: call.dispatch_key)
         end
 
-        # The entity half of `dry_run?`: refuses a port verb, which has no in-memory form.
-        # `to:`/`with:` are not keywords here; a key named either is an ordinary fact.
+        # The entity half of an in-memory run: refuses a port verb, which has no in-memory form.
+        # A `dry_run?` call has no `to`/`with`, so a key named either is an ordinary fact there.
         def dry_run_entity(call, domain, aggregate, command_name)
-          if aggregate.port(command_name.split(".", 2).first)
-            raise WiringError,
-                  "#{call.verb} names a port operation — dry_run? has no in-memory form for one, " \
-                  "only for aggregate and entity commands"
-          end
-
+          refuse_port_dry_run!(call, aggregate, command_name)
           resolution = nil
-          invocation = Invocation.from_call(call.verb, to: nil, with: nil, flat: call.flat, receiver: :entity) do
+          invocation = Invocation.from_call(call.verb, to: call.to, with: call.with, flat: call.flat,
+                                                       receiver: :entity) do
             (resolution = EntityInterpreter::Resolution.of(aggregate, command_name)).command
           end
           @entities.call(domain, aggregate, resolution, invocation, dry_run: true)
         end
 
+        def refuse_port_dry_run!(call, aggregate, command_name)
+          return unless aggregate.port(command_name.split(".", 2).first)
+
+          raise WiringError,
+                "#{call.verb} names a port operation — dry_run? has no in-memory form for one, " \
+                "only for aggregate and entity commands"
+        end
+
         def dry_run_aggregate(call, domain, aggregate, aggregate_name, command_name)
           command = command_of(aggregate, aggregate_name, command_name)
-          invocation = Invocation.from_call(call.verb, to: nil, with: nil, flat: call.flat) { command }
+          invocation = Invocation.from_call(call.verb, to: call.to, with: call.with, flat: call.flat) { command }
           @commands.call(domain, aggregate, command, invocation, dry_run: true)
         end
 
+        # The call for a verb whose receiver and facts arrive in one flat Hash: Symbol keys
+        # `:to`, `:with`, `:saga_correlation`, `:dispatch_key` are lifted out; the rest are facts.
+        def flat_call(verb, args)
+          facts = args.dup
+          Call.new(verb: verb, to: facts.delete(:to), with: facts.delete(:with),
+                   saga_correlation: facts.delete(:saga_correlation),
+                   dispatch_key: facts.delete(:dispatch_key), flat: facts)
+        end
+
+        # Runs a call through its interpreter in memory only, as `dry_run?` and `validate` do.
+        def dry_run_call(call)
+          domain, aggregate_name, command_name = parse(call.verb)
+          aggregate = resolve_aggregate(domain, aggregate_name, call.verb)
+          return dry_run_entity(call, domain, aggregate, command_name) if command_name.include?(".")
+
+          dry_run_aggregate(call, domain, aggregate, aggregate_name, command_name)
+        end
+
         def parse(verb)
           Naming.split_verb(verb) ||
             raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "not_fully_qualified", verb: verb))

data/lib/hecks/runtime/dispatcher/validating.rb

@@ -0,0 +1,73 @@
+require_relative "../collecting"
+require_relative "../validation"
+
+module Hecks
+  module Runtime
+    class Dispatcher
+      # Validation: a dry run that reports every reason a command would be refused.
+      module Validating
+        # Answers whether a command would be accepted right now, and if not, every reason.
+        #
+        # Runs the same pipeline as `dry_run?`, so nothing is saved, emitted or reacted to, but a
+        # stage that refuses finishes before the run stops, and a rule that loops reports every
+        # failure. The role is checked first and alone: a caller who may not run the command is told
+        # only that, and nothing the other rules would reveal.
+        #
+        # @param verb [String] the fully qualified aggregate or entity command verb
+        # @param args [Hash] the receiver and facts in one flat Hash, as `dispatch_flat` takes them:
+        #   Symbol keys `:to` and `:with` route, every other key is a fact
+        # @return [Runtime::Validation] the answer
+        # @raise [Runtime::WiringError] if the verb names a port operation
+        def validate(verb, args = {})
+          validation_of(flat_call(verb, args))
+        end
+
+        # Answers `validate`'s question of the facts as `dry_run?` reads them.
+        #
+        # Every key is a fact, `to` and `with` included, never routing, so this asks exactly what
+        # `dry_run?` was asked of the same keywords and differs only in reporting every reason.
+        #
+        # @param verb [String] the fully qualified aggregate or entity command verb
+        # @param args [Hash{Symbol => Object}] the facts as flat keywords, as `dry_run?` takes them
+        # @return [Runtime::Validation] the answer
+        # @raise [Runtime::WiringError] if the verb names a port operation
+        def validate_facts(verb, **args)
+          validation_of(Routing::Call.new(verb: verb, flat: args))
+        end
+
+        # Answers whether a record's lifecycle state lets a command run, reading no argument: the
+        # command's own `from:` guard and the aggregate's transitions, as the dispatch decides them.
+        #
+        # `validate` stops at the arguments stage when an argument is missing, so a caller asking
+        # what a record could do next, with no arguments yet, asks this as well.
+        #
+        # @param domain [String] the bluebook's name
+        # @param aggregate [Bluebook::Aggregate] the aggregate the record belongs to
+        # @param command [Bluebook::Command] the command asked about
+        # @param id [String] the record's identity
+        # @return [Boolean] false when the state refuses the command
+        def state_admits?(domain, aggregate, command, id)
+          instance = registry.repository(domain, aggregate).find(id)
+          rules = CommandRules.new(registry)
+          rules.enforce_lifecycle_guard(aggregate, command, instance)
+          rules.admissible_transition(aggregate, command, instance)
+          true
+        rescue LifecycleRefused
+          false
+        end
+
+        private
+
+        def validation_of(call)
+          Validation.new(Collecting.collect { attempt_dry_run(call) })
+        end
+
+        def attempt_dry_run(call)
+          dry_run_call(call)
+        rescue Hecks::Refused => e
+          Collecting.refuse(e)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/dispatcher/value_routing.rb

@@ -0,0 +1,54 @@
+module Hecks
+  module Runtime
+    class Dispatcher
+      # Routes a command value to the port operation a hecksagon binds to it: the operations whose
+      # `handles` name this command and value (ADR 0163 step 52). Mixed into {Routing}.
+      module ValueRouting
+        private
+
+        # The port operation a command value is routed to, or nil when no hecksagon binds the
+        # command by value. A command that has bindings refuses a value none of them names.
+        def value_handler(domain, aggregate, command, call)
+          key = command_key(aggregate, command)
+          bindings = value_bindings(domain, key)
+          return nil if bindings.empty?
+
+          supplied = supplied_values(call)
+          found = bindings.find { |_, value| supplied.include?(value) }
+          return found.first if found
+
+          no_value_handler!(key, bindings, supplied)
+        end
+
+        def command_key(aggregate, command) = "#{aggregate.name}.#{Naming.snake(command.hecks_name)}!"
+
+        # Every port operation of the domain's aggregates that names the command, with its value.
+        def value_bindings(domain, key)
+          bluebook = @registry.bluebook(domain)
+          return [] unless bluebook
+
+          handling_operations(bluebook).flat_map { |operation| bindings_of(operation, key) }
+        end
+
+        def handling_operations(bluebook) = bluebook.aggregates.flat_map(&:ports).flat_map(&:operations)
+
+        def bindings_of(operation, key)
+          operation.handles.select { |held| held[:command] == key }.map { |held| [operation, held[:value]] }
+        end
+
+        # The string values the call supplies, one level down from a value object
+        # (`target: {value:}`).
+        def supplied_values(call)
+          facts = (call.with || {}).merge(call.flat || {})
+          facts.values.flat_map { |value| value.is_a?(Hash) ? value.values : [value] }.grep(String)
+        end
+
+        def no_value_handler!(key, bindings, supplied)
+          handled = bindings.map { |_, value| value }.join(", ")
+          raise(UnknownVerb, "#{key} has no handler for #{supplied.inspect}; " \
+                             "its hecksagon handles #{handled.inspect}")
+        end
+      end
+    end
+  end
+end