hecks 1.4.0 → 1.5.1

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

@@ -23,6 +23,15 @@ module Hecks
         # Shared by CommandInterpreter and EntityInterpreter — an entity command
         # can declare a reference-typed attribute the same way an aggregate
         # command can, even though nothing in the real corpus does yet.
+        #
+        # @param domain [String, Symbol] the domain the referenced aggregate is
+        #   resolved in
+        # @param command [Class] the command or port-operation class (`Bluebook::Command`
+        #   or `PortOperation` subclass) whose reference-typed attributes are checked
+        # @param args [Hash{Symbol => Object}] the offered, already-coerced argument values
+        # @return [void]
+        # @raise [Runtime::NotFound] if a reference-typed argument names an identity that
+        #   does not exist in its target aggregate's repository
         def resolve_references(domain, command, args)
           command.attributes.each do |attribute|
             next unless attribute.reference?
@@ -41,6 +50,20 @@ module Hecks
         # Structural references are checked again against the settled state.
         # This is what makes a `has_many` declared on an aggregate honest even
         # when a command supplies its list through an ordinary typed argument.
+        #
+        # @param domain [String, Symbol] the domain the referenced aggregate is
+        #   resolved in
+        # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct
+        #   whose reference-typed attributes are checked against `state`
+        # @param state [Hash{Symbol => Object}] the settled, post-mutation state to
+        #   check every reference and relationship cardinality against
+        # @return [void]
+        # @raise [Runtime::TypeMismatch] if a required `has_one`/`belongs_to`
+        #   relationship holds nil
+        # @raise [Runtime::NotFound] if a reference-typed field names an identity
+        #   that does not exist in its target aggregate's repository
+        # @raise [Runtime::Unauthorized] if a referenced record belongs to a
+        #   different tenant than `construct`'s own record
         def resolve_state_references(domain, construct, state)
           own_tenant_field = tenant_field_for(construct)
 
@@ -73,6 +96,14 @@ module Hecks
         # checking only command arguments would let a required relationship be
         # persisted as nil. `has_many` admits zero members, so its empty list is
         # already a valid cardinality and needs no presence refusal.
+        #
+        # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct
+        #   `attribute` is declared on, named in a refusal
+        # @param attribute [Bluebook::Attribute] the reference-typed attribute to check
+        # @param held [Object, nil] the field's settled value
+        # @return [void]
+        # @raise [Runtime::TypeMismatch] if `attribute` declares a required (non-optional,
+        #   non-list) `has_one`/`belongs_to` relationship and `held` is nil
         def validate_relationship_cardinality(construct, attribute, held)
           return if attribute.relationship.nil? || attribute.list?
           return unless held.nil? && !attribute.optional?
@@ -84,15 +115,31 @@ module Hecks
         end
 
         # The reference resolves itself — through the chapter's own IR, so the
-        # bluebook's declared heads are the index. This used to regex the target's
-        # name out of "Reference<Customer>" and then search
-        # `registry.bluebook(domain).aggregates` for it — and later reached the
-        # target through Ruby's constant tree, a class thrown away for its `.ir`
-        # the moment it was found.
+        # bluebook's declared heads are the index, rather than regexing the
+        # target's name out of "Reference<Customer>" and searching
+        # `registry.bluebook(domain).aggregates` for it, or reaching the
+        # target through Ruby's constant tree, a class thrown away for its
+        # `.ir` the moment it was found.
+        #
+        # @param attribute [Bluebook::Attribute] the reference-typed attribute to resolve
+        # @return [Bluebook::Aggregate, nil] the target aggregate the reference names,
+        #   or nil if it cannot be resolved
+        # @raise [Bluebook::DSL::Malformed] if the reference does not know which
+        #   aggregate declares it
         def referenced_aggregate(attribute)
           attribute.type.resolve
         end
 
+        # Refuses a reference-typed value whose target identity does not exist.
+        #
+        # @param domain [String, Symbol] the domain `target` is resolved in
+        # @param target [Bluebook::Aggregate] the referenced aggregate
+        # @param held [Object, Array<Object>] the offered value: a single reference,
+        #   or, when `list:` is true, an Array of them
+        # @param list [Boolean] whether `held` is list-shaped
+        # @return [void]
+        # @raise [Runtime::NotFound] if any referenced identity does not exist in
+        #   `target`'s repository
         def validate_reference_values(domain, target, held, list:)
           values = list ? Array(held) : [held]
           values.each do |value|
@@ -132,6 +179,22 @@ module Hecks
         # — one change, both interpreters covered, no new vocabulary step
         # to keep in sync with `Vocabulary::AggregateDispatchOrder`/
         # `EntityDispatchOrder`.
+        #
+        # @param domain [String, Symbol] the domain `target` is resolved in
+        # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct
+        #   `attribute` is declared on, named in a refusal
+        # @param attribute [Bluebook::Attribute] the reference-typed attribute being
+        #   checked
+        # @param target [Bluebook::Aggregate] the referenced aggregate
+        # @param held [Object, Array<Object>] the offered value: a single reference,
+        #   or, when `attribute.list?` is true, an Array of them
+        # @param state [Hash{Symbol => Object}] `construct`'s own settled state, read
+        #   for its own tenant field's value
+        # @param own_tenant_field [Symbol, nil] `construct`'s own declared tenant field;
+        #   a no-op if nil or absent from `state`
+        # @return [void]
+        # @raise [Runtime::Unauthorized] if a referenced record's own tenant field
+        #   disagrees with `construct`'s
         def enforce_tenant_boundary(domain, construct, attribute, target, held, state, own_tenant_field)
           return unless own_tenant_field && state.key?(own_tenant_field)
 
@@ -172,11 +235,19 @@ module Hecks
         # (`Entity.queries` is always empty in the real corpus), so this
         # answers `nil` for every entity without needing to special-case
         # one.
+        #
+        # @param construct [Bluebook::Aggregate, Bluebook::Entity] the construct
+        #   whose declared queries are searched
+        # @return [Symbol, nil] the tenant-scoping field name, or nil if `construct`
+        #   declares no query with `authorize policy, tenant: :field`
         def tenant_field_for(construct)
           authorization = construct.queries.filter_map(&:authorization).find(&:tenant)
           authorization&.tenant&.to_sym
         end
 
+        # Renders a reference-typed value as the plain string key its target
+        # record is looked up by.
+        #
         # `value` is the referenced record's own id, exactly as `Identity.of`
         # would build it for that record — a bare scalar for a single-field
         # identity (the overwhelming common case; Banking's own plain
@@ -184,18 +255,23 @@ module Hecks
         # materialize_unwrapped` is a no-op passthrough here), or a
         # `Naming.identity`-joined string for a compound one
         # (`belongs_to Translation, as: :translation_ref` — Translation's
-        # own `identified_by :domain, :from, :to`, three fields). Before
-        # this, plain `value.to_s` on that compound case's own coerced
-        # Value hit Ruby's default `Object#to_s` (a raw, run-to-run-random
-        # memory address) instead of joining the record's real id — found
-        # live via bin/fuzz on the self-hosted "translation" domain
-        # (replay_is_deterministic), the same class of gap `Identity.from`
+        # own `identified_by :domain, :from, :to`, three fields). Without
+        # `materialize_unwrapped`, plain `value.to_s` on that compound case's
+        # own coerced Value would hit Ruby's default `Object#to_s` (a raw,
+        # run-to-run-random memory address) instead of joining the record's
+        # real id — found live via bin/fuzz on the self-hosted "translation"
+        # domain (replay_is_deterministic), the same class of gap `Identity.from`
         # already had for a compound `identified_by`'s own bare (undotted)
         # attribute paths. `materialize_unwrapped` recurses a multi-
         # attribute value object to a plain Hash keyed by attribute name,
         # in declaration order — `Naming.identity` on `.values` reproduces
         # the identical join `Identity.of` itself would produce for the
         # same fields.
+        #
+        # @param value [Object] the offered reference value: a `Runtime::Value`, a
+        #   scalar, or anything `Value.materialize_unwrapped` can open
+        # @return [String] the key to look the referenced record up by; empty when
+        #   `value` names no id
         def reference_key(value)
           unwrapped = Value.materialize_unwrapped(value)
           return Naming.identity(unwrapped.values).to_s if unwrapped.is_a?(Hash)
@@ -203,8 +279,8 @@ module Hecks
           unwrapped.to_s
         end
 
-        # A command argument's own related record, reachable by name from
-        # `given`/`ensures` — `disputed_by.status`, say, `CardPayment
+        # Hydrates a command argument's own related record, reachable by name
+        # from `given`/`ensures` — `disputed_by.status`, say, `CardPayment
         # .Dispute`'s own fresh `Reference<Customer>` argument — without
         # teaching the pure expression evaluator anything about
         # repositories. The lookup happens here, once, before evaluation;
@@ -213,23 +289,21 @@ module Hecks
         #
         # `owner` narrowed to `command` only (S12, ADR 0025 — "rules
         # confined to their own aggregate boundary"): dereferencing the
-        # declaring aggregate/entity's own stored `reference_to` used to
-        # be the other half of this method's job — a live query against
-        # another aggregate's own repository, every time a `given`/
-        # `ensures`/`invariant` ran. That half is gone; a cross-aggregate
-        # fact a rule needs now has to be a `projects`-maintained local
-        # field (`AggregateBuilder#projects_impl`'s own comment), already
-        # present in `subject`'s own state, no hydration needed. A
-        # reference-typed command argument stays in bounds, though — the
-        # ADR's own boundary list names "its command arguments" as
-        # readable, and nothing is stored yet for a fresh argument to
-        # project from; resolving it once here, synchronous with this
-        # command's own admission, is a different shape from a live query
-        # against an already-persisted reference. `enforce_givens`/
+        # declaring aggregate/entity's own stored `reference_to` is not part
+        # of this method's job — a cross-aggregate fact a rule needs has to
+        # be a `projects`-maintained local field (`AggregateBuilder#
+        # projects_impl`'s own comment), already present in `subject`'s own
+        # state, no hydration needed, rather than a live query against
+        # another aggregate's own repository on every `given`/`ensures`/
+        # `invariant` run. A reference-typed command argument stays in
+        # bounds, though — the ADR's own boundary list names "its command
+        # arguments" as readable, and nothing is stored yet for a fresh
+        # argument to project from; resolving it once here, synchronous
+        # with this command's own admission, is a different shape from a
+        # live query against an already-persisted reference. `enforce_givens`/
         # `enforce_ensures` are this method's only two remaining callers,
         # both passing `command`/`args`, never a `subject`'s own
-        # aggregate — verified before this comment was written, not
-        # assumed.
+        # aggregate — verified by grep, not assumed.
         #
         # Recurses into what it finds, so a chain deeper than one hop
         # still resolves in one pass. Depth-bounded rather than cycle-
@@ -239,6 +313,22 @@ module Hecks
         DEREFERENCE_DEPTH = 4
         private_constant :DEREFERENCE_DEPTH
 
+        # Hydrates `owner`'s own reference-typed attributes into the records they name.
+        #
+        # @param domain [String, Symbol] the domain a referenced aggregate is
+        #   resolved in
+        # @param owner [Class, Bluebook::Aggregate, Bluebook::Entity, nil] the
+        #   construct whose reference-typed attributes are dereferenced; nil (or a
+        #   depth of zero) short-circuits to an empty Hash
+        # @param source [Hash{Symbol => Object}] the offered payload to read each
+        #   reference-typed attribute's raw id from
+        # @param depth [Integer] how many more hops to recurse into a resolved
+        #   reference's own reference-typed fields
+        # @return [Hash{Symbol => Object}] one entry per resolved reference-typed
+        #   attribute, keyed by the attribute name with a trailing `_id` stripped,
+        #   valued at the referenced record's state merged with its own dereferenced
+        #   references; an attribute with no id, an unresolvable target, or no
+        #   matching record contributes nothing
         def dereference(domain, owner, source, depth: DEREFERENCE_DEPTH)
           return {} if depth <= 0 || owner.nil?
 

data/lib/hecks/runtime/dependency_planning.rb

@@ -17,12 +17,28 @@ module Hecks
         :unresolved_dependencies,
         keyword_init: true
       ) do
+        # Reports whether every owner field this command could touch is a known,
+        # deterministic write.
+        #
+        # @return [Boolean] `complete_state`
         def complete_state? = complete_state
+
+        # Reports whether the command needs no prior state at all (implies `complete_state?`).
+        #
+        # @return [Boolean] `state_independent`
         def state_independent? = state_independent
 
+        # Chooses the dispatch strategy this plan's proof and the adapter's own
+        # capabilities together allow.
+        #
         # Capability negotiation is correctness-first: an optimization is
         # selected only when both the semantic proof and adapter capability
         # are present. This is planning data only; no runtime path calls it yet.
+        #
+        # @param capabilities [Array<String, Symbol>] the repository's declared capabilities
+        # @return [Symbol] `DependencyPlanning::ATOMIC_PUT` when the plan is complete,
+        #   state-independent, and the adapter declares that capability;
+        #   `DependencyPlanning::TRANSACTIONAL_FALLBACK` otherwise
         def strategy_for(capabilities: [])
           return TRANSACTIONAL_FALLBACK unless complete_state? && state_independent?
           return TRANSACTIONAL_FALLBACK unless capabilities.map(&:to_sym).include?(ATOMIC_PUT)
@@ -38,13 +54,27 @@ module Hecks
       module ExpressionReads
         module_function
 
+        # Finds every dotted path a canonical expression reads, without evaluating it.
+        #
         # Read the same parsed canonical-expression nodes the evaluator uses.
         # A generic Struct walk keeps this additive when the expression grammar
         # gains a composed node; only Lookup nodes carry domain dependencies.
+        #
+        # @param canonical [String] the canonical expression text, such as a rule's `canonical`
+        # @return [Array<String>] the dotted paths the expression reads
         def paths(canonical)
           collect(Bluebook::Expression::Evaluator.parse(canonical), Set.new)
         end
 
+        # Walks one parsed expression node, collecting the dotted paths it reads.
+        #
+        # @param node [Object] a node from `Bluebook::Expression::Evaluator.parse` — a
+        #   `Bluebook::Expression::Resolver::Lookup`, a `Bluebook::Expression::Resolver::
+        #   BlockPredicate`, a `Struct` composed of further nodes, an `Array` of them, or any
+        #   other value (a literal), which contributes no paths
+        # @param bound_names [Set<String>] names locally bound by an enclosing block
+        #   predicate's own parameter, excluded from the result rather than reported as reads
+        # @return [Array<String>] the dotted paths read under `node`, excluding `bound_names`
         def collect(node, bound_names)
           case node
           when Bluebook::Expression::Resolver::Lookup
@@ -87,8 +117,20 @@ module Hecks
         # unresolved regardless of correctness. Defaults to `aggregate`
         # (a no-op) for the plain-aggregate case — `CommandInterpreter`'s
         # own call site never needed to change.
+        #
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct the command
+        #   is dispatched against; an entity for an entity-owned command
+        # @param command [Bluebook::Command] the command to analyze
+        # @param root_aggregate [Bluebook::Aggregate] the owning aggregate a `parent.*` read
+        #   resolves against; defaults to `aggregate` for a plain-aggregate command
+        # @return [Hecks::Runtime::DependencyPlanning::Plan] the derived, frozen plan
         def self.call(aggregate:, command:, root_aggregate: aggregate) = new(aggregate, command, root_aggregate).call
 
+        # @param aggregate [Bluebook::Aggregate, Bluebook::Entity] the construct the command
+        #   is dispatched against
+        # @param command [Bluebook::Command] the command to analyze
+        # @param root_aggregate [Bluebook::Aggregate] the owning aggregate `parent.*` reads
+        #   resolve against; defaults to `aggregate`
         def initialize(aggregate, command, root_aggregate = aggregate)
           @aggregate = aggregate
           @command = command
@@ -126,6 +168,9 @@ module Hecks
           @unresolved = Set.new
         end
 
+        # Runs the analysis and derives the command's dependency plan.
+        #
+        # @return [Hecks::Runtime::DependencyPlanning::Plan] the derived, frozen plan
         def call
           analyze_initial_state
           analyze_mutations

data/lib/hecks/runtime/dispatcher.rb

@@ -1,5 +1,4 @@
 require_relative "errors"
-require_relative "../deprecation"
 require_relative "refusal_wording"
 require_relative "caller"
 require_relative "invocation"
@@ -121,22 +120,21 @@ module Hecks
       # Runs one command, entity command or port operation, then every policy and saga reaction
       # its events are owed.
       #
-      # Loose keyword facts are deprecated (roadmap I3) — `dispatch(verb,
-      # amount: 5)` still works, and warns once per call site; pass
-      # `with: { amount: 5 }` (and the receiver in `to:`) instead. The
-      # keyword door closes in `LEGACY_ARGS_REMOVAL`. `bin/codemod_legacy_
-      # dispatch_args` rewrites existing callers.
+      # The receiver in `to:`, the facts in `with:`, and nothing else.
+      # Loose keyword facts — `dispatch(verb, amount: 5)`, one bag holding
+      # both the route and the payload — were deprecated in 1.3.x and are
+      # gone: Ruby now refuses them itself, by name ("unknown keyword:
+      # :amount"). Code holding a bag of data rather than written keywords
+      # calls `dispatch_flat` below; that door is not going anywhere.
       #
       # @param verb [String] the fully qualified verb: `"Domain::Aggregate.Command"`,
       #   `"Domain::Aggregate.Entity.Command"` or `"Domain::Aggregate.Port.Operation"`
       # @param to [String, Hash, nil] the receiver: an aggregate identity, or an entity route
       #   Hash with `:aggregate` and one of `:entity`/`:entities`; nil when the facts carry
       #   the identity themselves
-      # @param with [Hash, nil] the command's facts, keyed by argument name (String or Symbol);
-      #   may not be combined with loose keyword facts
+      # @param with [Hash, nil] the command's facts, keyed by argument name (String or Symbol)
       # @param saga_correlation [Hash, nil] correlation head => value, stamped on every
       #   emitted event when a saga leg causes this dispatch; nil otherwise
-      # @param legacy_args [Hash{Symbol => Object}] deprecated loose keyword facts
       # @return [Runtime::Dispatcher::Result] the verb, settled instance (nil for a port
       #   operation), emitted events, execution plan and persistence outcome
       # @raise [Runtime::UnknownVerb] if the verb is not fully qualified, or names a domain,
@@ -145,39 +143,20 @@ module Hecks
       #   the call (`GivenNotMet`, `TypeMismatch`, `Unauthorized`, `NotFound`, …)
       # @raise [Runtime::StaleWrite] if concurrent writers beat this one through every retry
       # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
-      # @raise [Deprecation::Error] if loose keyword facts are given where
-      #   `Deprecation.raise_on!(:legacy_dispatch_args)` applies
-      def dispatch(verb, to: nil, with: nil, saga_correlation: nil, **legacy_args)
-        Dispatcher.deprecate_loose_facts(legacy_args)
-        dispatch_invocation(verb, to: to, with: with, saga_correlation: saga_correlation, legacy_args: legacy_args)
-      end
-
-      LEGACY_ARGS_REMOVAL = "1.5.0".freeze
-      LEGACY_ARGS_WARNING =
-        "passing command facts to dispatch as loose keyword arguments is deprecated and will be removed in " \
-        "hecks #{LEGACY_ARGS_REMOVAL} — pass them as `with: { ... }`, with the receiver identity in `to:` " \
-        "(bin/codemod_legacy_dispatch_args rewrites existing callers)".freeze
-
-      # Warns, once per call site, that a dispatch passed its facts as loose keyword arguments.
-      #
-      # @param legacy_args [Hash] the loose keyword facts a dispatch received; empty means
-      #   nothing deprecated was used, and nothing is warned
-      # @return [nil] always, whether or not a warning was issued
-      # @raise [Deprecation::Error] if `legacy_args` is not empty where
-      #   `Deprecation.raise_on!(:legacy_dispatch_args)` applies
-      def self.deprecate_loose_facts(legacy_args)
-        Deprecation.call(:legacy_dispatch_args, LEGACY_ARGS_WARNING) unless legacy_args.empty?
+      def dispatch(verb, to: nil, with: nil, saga_correlation: nil)
+        dispatch_invocation(verb, to: to, with: with, saga_correlation: saga_correlation, flat: {})
       end
 
       # Dispatches a verb whose receiver and facts arrive together in one flat Hash.
       #
-      # **The flat-facts wire form** — one Hash, not keywords, and not
-      # deprecated: the shape `spec/corpus/*.json` steps, the Rust kernel's
-      # `cli.rs` contract, a reaction without a `with:` projection, and the
-      # self-hosted meta-domain all carry. Routes exactly as
-      # `dispatch(verb, **args)` does: a Symbol `:to`, `:with` or
+      # **The flat-facts wire form** — one Hash, not keywords: the shape
+      # `spec/corpus/*.json` steps, the Rust kernel's `cli.rs` contract, a
+      # reaction without a `with:` projection, and the self-hosted
+      # meta-domain all carry, where the receiver's identity is one of the
+      # keys because that is how the wire spells it. Routes exactly as the
+      # removed keyword door did: a Symbol `:to`, `:with` or
       # `:saga_correlation` key is lifted out as that keyword, everything
-      # else is a fact (so a String "to" key stays a fact).
+      # else is a fact (so a String "to" key stays a fact, as it did).
       # Framework code that replays data calls this; application code
       # calls `dispatch(verb, to:, with:)`.
       #
@@ -196,10 +175,10 @@ module Hecks
         to = facts.delete(:to)
         with = facts.delete(:with)
         saga_correlation = facts.delete(:saga_correlation)
-        dispatch_invocation(verb, to: to, with: with, saga_correlation: saga_correlation, legacy_args: facts)
+        dispatch_invocation(verb, to: to, with: with, saga_correlation: saga_correlation, flat: facts)
       end
 
-      def dispatch_invocation(verb, to:, with:, saga_correlation:, legacy_args:)
+      def dispatch_invocation(verb, to:, with:, saga_correlation:, flat:)
         domain, aggregate_name, command_name = parse(verb)
         aggregate = resolve_aggregate(domain, aggregate_name, verb)
 
@@ -222,12 +201,12 @@ module Hecks
               operation = port.operation(sub) ||
                           raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "port_no_operation",
                                                                         port: head, operation: sub))
-              invocation = Invocation.from_call(verb, to: to, with: with, legacy: legacy_args,
+              invocation = Invocation.from_call(verb, to: to, with: with, flat: flat,
                                                       receiver: :port, aggregate: aggregate) { operation }
               [nil, @port_ops.call(domain, aggregate, operation, invocation), nil, nil, :enqueue]
             else
               resolution = nil
-              invocation = Invocation.from_call(verb, to: to, with: with, legacy: legacy_args,
+              invocation = Invocation.from_call(verb, to: to, with: with, flat: flat,
                                                       receiver: :entity, entity_depth: command_name.count(".")) do
                 (resolution = EntityInterpreter::Resolution.of(aggregate, command_name)).command
               end
@@ -235,7 +214,7 @@ module Hecks
             end
           else
             command = command_of(aggregate, aggregate_name, command_name)
-            invocation = Invocation.from_call(verb, to: to, with: with, legacy: legacy_args) { command }
+            invocation = Invocation.from_call(verb, to: to, with: with, flat: flat) { command }
             @commands.call(domain, aggregate, command, invocation, saga_correlation)
           end
 
@@ -328,13 +307,13 @@ module Hecks
           # `to:`/`with:` are not keywords of this method — a key named
           # either is an ordinary fact here (BUG#131), so both go in as nil.
           resolution = nil
-          invocation = Invocation.from_call(verb, to: nil, with: nil, legacy: args, receiver: :entity) do
+          invocation = Invocation.from_call(verb, to: nil, with: nil, flat: args, receiver: :entity) do
             (resolution = EntityInterpreter::Resolution.of(aggregate, command_name)).command
           end
           @entities.call(domain, aggregate, resolution, invocation, dry_run: true)
         else
           command = command_of(aggregate, aggregate_name, command_name)
-          invocation = Invocation.from_call(verb, to: nil, with: nil, legacy: args) { command }
+          invocation = Invocation.from_call(verb, to: nil, with: nil, flat: args) { command }
           @commands.call(domain, aggregate, command, invocation, dry_run: true)
         end
 
@@ -360,7 +339,9 @@ module Hecks
       # @param to [String, Hash, nil] the receiving aggregate's identity; when nil it is read
       #   from the facts, by the operation's reference or identity attribute
       # @param with [Hash, nil] the operation's facts, keyed by argument name
-      # @param legacy_args [Hash{Symbol => Object}] deprecated loose keyword facts
+      # @param flat [Hash] the wire form `dispatch_flat` takes, for the driving adapter
+      #   holding a decoded webhook rather than written keywords; it is where the operation's
+      #   own reference attribute is read from and lifted into `to:` when `to:` is nil
       # @return [Array<Runtime::Event>] the events the operation announced: one per declared
       #   `emits` for an inbound operation, the one answering or refusing event for an
       #   outbound one
@@ -369,10 +350,7 @@ module Hecks
       #   is malformed
       # @raise [Runtime::NotFound] if the receiving aggregate record does not exist
       # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
-      # @raise [Deprecation::Error] if loose keyword facts are given where
-      #   `Deprecation.raise_on!(:legacy_dispatch_args)` applies
-      def dispatch_port(domain, aggregate_name, port_name, operation_name, to: nil, with: nil, **legacy_args)
-        Dispatcher.deprecate_loose_facts(legacy_args)
+      def dispatch_port(domain, aggregate_name, port_name, operation_name, to: nil, with: nil, flat: {})
         aggregate = resolve_aggregate(domain, aggregate_name, "#{domain}::#{aggregate_name}.#{port_name}.#{operation_name}")
         port = aggregate.port(port_name) ||
                raise(UnknownVerb, "#{aggregate_name} has no port #{port_name.inspect}")
@@ -380,7 +358,7 @@ module Hecks
                     raise(UnknownVerb, "#{port_name} has no operation #{operation_name.inspect}")
 
         invocation = Invocation.from_call("#{domain}::#{aggregate_name}.#{port_name}.#{operation_name}",
-                                          to: to, with: with, legacy: legacy_args,
+                                          to: to, with: with, flat: flat,
                                           receiver: :port, aggregate: aggregate) { operation }
         announced = @port_ops.call(domain, aggregate, operation, invocation)