hecks 0.2.0 → 1.0.0

data/lib/hecks/runtime/policy_interpreter.rb

@@ -0,0 +1,366 @@
+require_relative "../naming"
+require_relative "errors"
+require_relative "query_interpreter"
+require_relative "reaction_invocation"
+require_relative "refusal_wording"
+require_relative "value"
+require_relative "../bluebook/expression/evaluator"
+
+module Hecks
+  module Runtime
+    class PolicyInterpreter
+      attr_reader :registry
+
+      def initialize(registry, door:)
+        @registry = registry
+        @door     = door
+      end
+
+      # `deliver` returns `nil` for a policy whose `where` did not hold —
+      # SILENTLY, the same as a policy `policies_for` never selected at all
+      # (an `event_qualifier` miss carries no reaction_log entry either) —
+      # so nothing is appended for it. A `for_each` policy answers an ARRAY
+      # (one record per matched row) rather than one record ; `Array(...)`
+      # is wrong here (it would explode a plain record Hash into its own
+      # key/value pairs), so the two shapes are told apart explicitly.
+      def react(event, domain)
+        policies_for(event).each do |policy, home_domain|
+          result = deliver(policy, event, home_domain)
+          next if result.nil?
+
+          (result.is_a?(Array) ? result : [result]).each { |record| @registry.reaction_log << record }
+        end
+      end
+
+      private
+
+      # SCANS EVERY LOADED BLUEBOOK, not just the emitting command's own —
+      # a policy commonly lives in the CONSUMER's bluebook, reacting
+      # passively to an event a different domain's aggregate emits (the
+      # corpus-standard shape : `world/conception/bluebook/domain_cell.bluebook`'s
+      # ConceiveOnAbsorption reacts `on "DomainAbsorbed"`, an event
+      # `body/organs/bluebook/gut.bluebook`'s Gut.Absorb emits — two
+      # different bluebooks, joined only by the event's NAME). Restricting
+      # the scan to the emitting domain's own bluebook (the previous
+      # shape) silently drops every cross-domain reaction : the policy is
+      # never even a candidate, no refusal, no log entry, nothing —
+      # confirmed against the corpus's own .behaviors fixtures, several of
+      # which encode this exact cross-bluebook cascade as their contract.
+      #
+      # Returns [policy, home_domain] pairs rather than bare policies —
+      # `deliver`/`deliver_for_each` fall back to the REACTING policy's
+      # OWN domain (not the emitting one) when a trigger or for_each route
+      # is bare, and that fallback has to travel with each match now that
+      # a single event can surface policies from several different homes.
+      def policies_for(event)
+        emitting = Naming.demodulise(event.aggregate)
+
+        @registry.bluebooks.each_value.flat_map do |bluebook|
+          matching = bluebook.policies.select do |policy|
+            policy.event_name == event.name &&
+              (policy.event_qualifier.nil? || policy.event_qualifier == emitting)
+          end
+          matching.map { |policy| [policy, bluebook.name] }
+        end
+      end
+
+      # THE GUARD, evaluated against the triggering event's own payload —
+      # a policy has no aggregate instance of its own to read state from,
+      # so `state` is empty and every bare name a `where` resolves comes
+      # from `attrs` (Expression::Resolver#fetch checks `attrs` before
+      # `state`, so this is exactly the shape `enforce_givens` already
+      # gives a command's own given, minus the settled-record half a
+      # policy simply has none of). Called from inside `deliver`'s own
+      # rescue-guarded body (both callers, below) — never guarded here —
+      # so an EvaluationError (an unresolvable field, a bad comparison) is
+      # caught the SAME way any other reaction defect is, not swallowed as
+      # though the policy had merely declined to fire.
+      def where_holds?(policy, event)
+        return true if policy.where.to_s.empty?
+
+        Bluebook::Expression::Evaluator.call(policy.where, {}, event.payload.transform_keys(&:to_sym))
+      end
+
+      def deliver(policy, event, domain)
+        # `record` ASSIGNED BEFORE ANY BRANCH THAT CAN RAISE, same reason
+        # `deliver_for_each`'s own header gives : both rescue clauses below
+        # call `.merge` on it, and a defect raised before it existed would
+        # be caught here only to raise a second, different NoMethodError
+        # trying to record the first one.
+        target = "#{policy.target_domain || domain}::#{policy.trigger_command}"
+        record = { policy: policy.name, on: event.name, trigger: target }
+
+        return deliver_for_each(policy, event, domain, target, record) unless policy.for_each.to_s.empty?
+        return nil unless where_holds?(policy, event)
+
+        if @door.reaction_depth_reached?
+          return record.merge(delivered: false,
+                              reason:    "reaction depth #{@door.max_reaction_depth} reached")
+        end
+
+        args = trigger_args(policy, event)
+        @door.reenter(target, **reaction_invocation(target, args, policy, event))
+        record.merge(delivered: true)
+      rescue *DOMAIN_REFUSALS => error
+        # The target refused — a fact about the domain, recorded and not
+        # fatal to the command that emitted the event.
+        record.merge(delivered: false, reason: error.message)
+      rescue StandardError => error
+        # A DEFECT, not a refusal — a NoMethodError in an interpreter, a
+        # NameError from a missing constant, a TypeError from a bad
+        # assumption : exactly the class of thing DOMAIN_REFUSALS
+        # (errors.rb, see the comment above that constant) deliberately
+        # excludes, and for the reason that comment gives at length —
+        # folding a crash into the same `delivered: false` shape as an
+        # ordinary refusal makes a broken runtime read as normal operation
+        # in the log. This clause does not reopen that hole: it is a
+        # SECOND, narrower rescue, tried only once the first one above has
+        # already declined to match, so a legitimate refusal still takes
+        # the branch above and a defect always takes this one.
+        #
+        # Catching it HERE is safe for a fact this method's caller cannot
+        # see from where it sits: by the time `react` runs, the command
+        # that EMITTED `event` has already succeeded and PERSISTED —
+        # `Dispatcher#dispatch` calls `@policies.react` only after its own
+        # `announced` events are already in hand. Letting this exception
+        # keep propagating would not undo that command (nothing here is
+        # transactional across aggregates) — it would only blow up the
+        # ORIGINAL caller's `dispatch` call for a failure that happened in
+        # a DIFFERENT command, one the caller never asked to run and has no
+        # way to compensate for. So the defect is recorded, distinguishably
+        # (`defect: true`, plus the error's own class — nothing here is
+        # allowed to read like an ordinary refusal), warned to STDERR so it
+        # is never silent, and left exactly where it happened for a human
+        # to find — never re-raised, and never swallowed either.
+        warn "[hecks] defect in reaction — policy #{policy.name} on #{event.name} " \
+             "firing #{target}: #{error.class}: #{error.message}"
+        record.merge(delivered: false, reason: error.message, defect: true, error_class: error.class.name)
+      end
+
+      # THE FAN-OUT — `policy.for_each` names a query ; this runs it
+      # against the triggering event's own payload (the same source
+      # `deliver`'s own ordinary path forwards to `trigger` wholesale) and
+      # fires `trigger` once per row, merging each row's own id into the
+      # forwarded payload under whichever key THE TARGET COMMAND ITSELF
+      # expects to be addressed by (`Behaviour::Command#addressing_key_for`
+      # — never a guessed, one-size mint: `Account.Freeze`, addressed by
+      # `account` because it is declared ON Account and self-references
+      # it, refused every dispatch for as long as this hardcoded
+      # `<aggregate>_id` instead — a real bug, found wiring `for_each`
+      # into a real domain for the first time, not a hypothetical). A
+      # refusal is recorded per row and the fan-out continues ; a crash
+      # resolving the QUERY ITSELF, or the TARGET COMMAND'S OWN inability
+      # to address this aggregate at all (`addressing_key_for` answering
+      # `nil` — a domain-authoring mistake, not a data problem), is a
+      # single top-level defect for the policy, the same shape `deliver`'s
+      # own outer rescue already gives every other reaction.
+      def deliver_for_each(policy, event, domain, target, record)
+        return nil unless where_holds?(policy, event)
+
+        query_domain, aggregate_name, query_name = policy.for_each_route(domain)
+        aggregate = resolve_query_aggregate(query_domain, aggregate_name, policy.for_each)
+        # THE QUERY READS THE EVENT, never the projection — `with:` says
+        # what the TRIGGER is given, and the fan-out's query is asking a
+        # different question (WHICH rows) in the event's own vocabulary.
+        query_args    = for_each_query_args(aggregate.query(query_name), event)
+        rows          = QueryInterpreter.new(@registry).call(query_domain, aggregate, query_name, query_args)
+        reference_key = addressing_key_for(target, aggregate_name)
+
+        Array(rows).map do |row|
+          deliver_for_each_row(target, record, trigger_args(policy, event, reference_key => row[:id]), row, policy, event)
+        end
+      rescue *DOMAIN_REFUSALS => error
+        record.merge(delivered: false, reason: error.message)
+      rescue StandardError => error
+        warn "[hecks] defect in reaction — policy #{policy.name} on #{event.name} " \
+             "resolving for_each #{policy.for_each}: #{error.class}: #{error.message}"
+        record.merge(delivered: false, reason: error.message, defect: true, error_class: error.class.name)
+      end
+
+      # THE EVENT'S OWN IDENTITY IS A FACT TOO, not only its payload. A
+      # for_each query commonly filters by the EMITTING record's own
+      # identity (`OpenForCustomer`'s own `reference:`, scoping by the
+      # very customer who was just suspended) — which used to arrive for
+      # free because LEGACY dispatch left the self-addressing key riding
+      # along in `event.payload` unfiltered. Routing separated from
+      # payload (`to:`/`with:`, what the facade's own bang-methods always
+      # use) correctly stopped carrying it there, which left this query
+      # silently seeing NEITHER the field it needs NOR any error saying
+      # why — an empty result read as "nothing to freeze" instead of "the
+      # customer" the whole reaction exists to catch.
+      #
+      # Merged in ONLY when the query declares an argument by that exact
+      # name AND the emitting aggregate's own identity is genuinely what
+      # that name means (`construct.identity_heads`) — the same guard
+      # `SagaInterpreter::Correlation#self_identified?` uses for the
+      # identical shape one call away, so an unrelated aggregate sharing
+      # an argument name by coincidence never gets misread as this one.
+      # Never overrides a value the payload already supplied.
+      def for_each_query_args(query, event)
+        args = event.payload.transform_keys(&:to_sym)
+        return args unless query
+
+        domain, bare_name = event.aggregate.to_s.split("::", 2)
+        construct = bare_name && @registry.bluebook(domain)&.aggregate(bare_name)
+        return args unless construct
+
+        heads = construct.identity_heads.map(&:to_s)
+        query.attributes.each do |attribute|
+          next if args.key?(attribute.name)
+          next unless heads.include?(attribute.name.to_s)
+
+          args[attribute.name] = event.id
+        end
+        args
+      end
+
+      # WHAT THE TRIGGER IS GIVEN. Undeclared, the event's whole payload
+      # forwards verbatim — the behaviour every policy had before `with:`
+      # existed, and still the right default for a trigger shaped like
+      # its event.
+      #
+      # Declared, it is the same reading a saga's own `dispatch ...,
+      # with:` gets (`SagaInterpreter#dispatch_args`): a Symbol names a
+      # field on the SOURCE below, anything else is a literal the policy
+      # supplies itself. A saga additionally resolves against its own
+      # memory and correlation key; a policy has neither — it holds
+      # nothing between events — so the source is the event, plus:
+      #
+      # `extra` is a FAN-OUT'S ROW KEY, merged into the source BEFORE the
+      # projection rather than after it. That is what lets a `for_each`
+      # policy name the row it is acting on — `with: { account: :account }`
+      # — and therefore what lets one send the row and NOTHING ELSE. A
+      # trigger needing only which record to act on is the ordinary case
+      # for a fan-out, and before this it could not be written: the whole
+      # event rode along, and the target had to declare every field of it
+      # whether it read them or not.
+      def trigger_args(policy, event, extra = {})
+        payload = event.payload.transform_keys(&:to_sym).merge(extra)
+        return payload unless ReactionInvocation.projection_declared?(policy)
+
+        payload = emitter_identity(event).merge(payload)
+
+        args = ReactionInvocation.resolve_mapping(
+          with_spec: policy.with_spec,
+          scopes:    [["event payload and fan-out row", payload]],
+          label:     "#{policy.name}'s trigger"
+        )
+
+        # THE RAW INPUTS `args` WAS RESOLVED FROM — same additive,
+        # Ruby-only shape SagaInterpreter#deliver_saga_dispatch's own
+        # saga_dispatch_log gets, for Properties.dispatch_binding_
+        # fidelity's own independent re-derivation of Policy#with_spec's
+        # 2-branch resolution (Symbol → payload lookup, anything else →
+        # literal — a policy holds no correlation and no memory, so
+        # `payload` — the merged event-payload-plus-fan-out-row source —
+        # is the WHOLE source, unlike a saga's own 4-branch one).
+        @registry.policy_dispatch_log << { policy: policy.name, on: event.name, payload: payload,
+                                            with_spec: policy.with_spec, args: args }
+        args
+      end
+
+      # THE EMITTING RECORD'S OWN IDENTITY IS A FACT A PROJECTION MAY READ
+      # — the same reasoning `for_each_query_args` gives one method up,
+      # extended from the fan-out's QUERY to the trigger's own `with:`.
+      # Routing separated from payload (`to:`/`with:`) stopped carrying
+      # the emitting aggregate's identity in the payload, which is right
+      # for the event (a KnightCaptured is a fact about a knight, not a
+      # re-statement of which game) but left a CROSS-aggregate reaction
+      # with no way to say which record to address: chess's Graveyard is
+      # one-per-game, fed by policy from every piece's own Captured
+      # event, and its burials had no way to name the game — the
+      # dispatcher fell through to the captured piece's `id` as the
+      # graveyard's identity and refused every one ("no Graveyard with
+      # label.value \"bb\""). Same-aggregate targets were already covered
+      # (`ReactionInvocation.source_receiver_for` lifts Event.id), so
+      # this is the OTHER aggregate's half of that.
+      #
+      # Offered under the emitting aggregate's own identity heads, only
+      # to an EXPLICIT projection (a legacy wholesale forward keeps its
+      # exact old payload), and never over a value the payload itself
+      # carries. `event.id` is the scalar the identity resolves to, so a
+      # projection naming it as the target's own identity head routes it
+      # as the receiver (`Identity.of` coerces a scalar against a
+      # single-field VO head), and one naming it as a declared attribute
+      # carries it as a fact. The build-time validator admits the same
+      # names (`BluebookBuilder.check_with_spec!`).
+      def emitter_identity(event)
+        return {} if event.id.nil? || event.id.to_s.empty?
+
+        domain, bare_name = event.aggregate.to_s.split("::", 2)
+        construct = bare_name && @registry.bluebook(domain)&.aggregate(bare_name)
+        return {} unless construct
+
+        construct.identity_heads.to_h { |head| [head.to_sym, event.id] }
+      end
+
+      # RESOLVES `target` ("Domain::Aggregate.Command", the same shape
+      # `deliver`'s own caller already built) back to its OWN declared
+      # command, then asks IT how it expects to be addressed by a row of
+      # `aggregate_name` — see `Behaviour::Command#addressing_key_for`'s
+      # own comment for the two shapes that answers. Raises (caught by
+      # `deliver_for_each`'s own outer `rescue StandardError`, the same
+      # "a defect, not a refusal" treatment `resolve_query_aggregate`'s
+      # own `UnknownVerb` already gets one level up) rather than
+      # silently falling back on a guess when the target command cannot
+      # be resolved, or genuinely cannot be addressed by this aggregate
+      # at all — either is a domain-authoring mistake worth surfacing
+      # loudly, not a row this fan-out simply skips.
+      def addressing_key_for(target, aggregate_name)
+        target_domain, target_aggregate_name, target_command_name = Naming.split_verb(target)
+        command = @registry.bluebook(target_domain)&.aggregate(target_aggregate_name)&.command(target_command_name)
+        raise UnknownVerb, "for_each's own trigger #{target.inspect} does not resolve to a declared command" unless command
+
+        key = command.addressing_key_for(aggregate_name)
+        return key if key
+
+        raise ArgumentError,
+              "#{target} cannot be addressed by a row of #{aggregate_name} — it declares no self-reference to " \
+              "#{aggregate_name} and no reference-typed attribute targeting it"
+      end
+
+      def deliver_for_each_row(target, record, args, row, policy, event)
+        row_record = record.merge(for_row: row[:id])
+
+        if @door.reaction_depth_reached?
+          return row_record.merge(delivered: false,
+                                  reason:    "reaction depth #{@door.max_reaction_depth} reached")
+        end
+
+        # ALREADY MERGED, by `trigger_args` — the row key belongs in the
+        # source a `with:` projection reads FROM, not bolted onto its
+        # result, or a projection could never name the row it acts on.
+        @door.reenter(target, **reaction_invocation(target, args, policy, event))
+        row_record.merge(delivered: true)
+      rescue *DOMAIN_REFUSALS => error
+        row_record.merge(delivered: false, reason: error.message)
+      end
+
+      def reaction_invocation(target, args, policy, event)
+        ReactionInvocation.build(
+          registry:        @registry,
+          verb:            target,
+          projected:       args,
+          explicit:        ReactionInvocation.projection_declared?(policy),
+          source_receiver: { aggregate: event.aggregate, identity: event.id }
+        )
+      end
+
+      # `for_each`'s own QUERY route moved onto the Policy itself
+      # (Behaviour::Policy#for_each_route) — one reading the interpreter
+      # and the fuzzer's fan-out property both call, rather than the
+      # same split spelled twice. The reference-KEY the dispatch itself
+      # uses is `addressing_key_for`, above — a property of the TARGET
+      # COMMAND, not of the policy, so it lives on `Behaviour::Command`
+      # instead.
+
+      def resolve_query_aggregate(domain, aggregate_name, verb)
+        bluebook = @registry.bluebook(domain) ||
+                   raise(UnknownVerb, RefusalWording.render("UnknownVerb", "no_domain", domain: domain.inspect, verb: verb))
+        bluebook.aggregate(aggregate_name) ||
+          raise(UnknownVerb, RefusalWording.render("UnknownVerb", "no_aggregate",
+                                                   domain: domain, aggregate: aggregate_name.inspect))
+      end
+    end
+  end
+end

data/lib/hecks/runtime/port_operation_interpreter.rb

@@ -0,0 +1,210 @@
+require_relative "interpreting"
+require_relative "command_interpreter/argument_gate"
+require_relative "event"
+require_relative "value"
+require_relative "../naming"
+
+module Hecks
+  module Runtime
+    # The dispatch pipeline for a port operation — called by an adapter living
+    # outside the bluebook entirely, never by the domain itself. Deliberately
+    # a trimmed CommandInterpreter: the same payload gate and coercion
+    # (ArgumentGate, Interpreting#normalize_args), but no `given`, no
+    # `mutations`, no lifecycle, no save. A port operation does not act on an
+    # aggregate instance — it translates an external call into an event in
+    # this domain's own vocabulary, and whatever mutation follows happens
+    # wherever a `policy` reacts to that event, exactly as it would for any
+    # command-emitted one.
+    class PortOperationInterpreter
+      include Interpreting
+      include CommandInterpreter::ArgumentGate
+
+      Context = Struct.new(:domain, :aggregate, :operation, :args, :route, :instance, :result)
+
+      DISPATCH_ORDER = %i[
+        refuse_unknown_arguments refuse_absent_arguments normalize_args resolve_references resolve_route emit
+      ].freeze
+
+      def initialize(registry, rules:)
+        @registry = registry
+        @rules    = rules
+      end
+
+      def call(domain, aggregate, operation, args, route:)
+        ctx = Context.new(domain, aggregate, operation, args)
+        ctx.route = route
+        run_dispatch_order(DISPATCH_ORDER, ctx)
+        ctx.result
+      end
+
+      private
+
+      def step_refuse_unknown_arguments(ctx)
+        step(:refuse_unknown_arguments) { refuse_unknown_arguments(ctx.domain, ctx.aggregate, ctx.operation, ctx.args) }
+      end
+
+      def step_refuse_absent_arguments(ctx)
+        step(:refuse_absent_arguments) { refuse_absent_arguments(ctx.operation, ctx.args, aggregate: ctx.aggregate) }
+      end
+
+      def step_normalize_args(ctx)
+        ctx.args = step(:normalize_args) { normalize_args(ctx.aggregate, ctx.operation, ctx.args) }
+      end
+
+      def step_resolve_references(ctx)
+        step(:resolve_references) { @rules.resolve_references(ctx.domain, ctx.operation, ctx.args) }
+      end
+
+      def step_resolve_route(ctx)
+        ctx.instance = step(:resolve_route) do
+          @registry.repository(ctx.domain, ctx.aggregate).find(ctx.route.aggregate) ||
+            raise(NotFound, "#{ctx.aggregate.hecks_name} #{ctx.route.aggregate.inspect} does not exist")
+        end
+      end
+
+      def step_emit(ctx)
+        ctx.result = step(:emit) { ctx.operation.outbound? ? ask(ctx) : emit(ctx) }
+      end
+
+      # THE DOMAIN CALLING OUT, AND BOTH ENDINGS RECORDED.
+      #
+      # The adapter is found the same way every other port's is — by name,
+      # across whatever adapters this boot loaded — so an `asks` is bound by
+      # an adapter declaring `port "IssueTracker"` and nothing new to learn.
+      #
+      # EVERY FAILURE IS AN ANSWER. A raise from the far side of a boundary is
+      # not an exception in this domain's terms, it is the outside saying no,
+      # and the chapter already named the word for that. So the rescue is
+      # deliberately wide: a timeout, a bad credential, an adapter that does
+      # not exist, a nil where a number was wanted — all of them become the
+      # `refuses` event, carrying what was said. A policy reacts to it, a
+      # retry counter reads it, and nothing has to catch anything.
+      #
+      # AN ASK IS HANDED THE RECORD IT IS ABOUT.
+      #
+      # An INBOUND operation deliberately cannot read state — it is the
+      # anti-corruption boundary, translating a fact from outside, and letting
+      # it read the aggregate would make it a second place rules live. That
+      # rule was written for that direction and does not survive the crossing.
+      #
+      # An outbound one almost always needs the record. `asks "File"` names
+      # `reference_to Ticket` and the adapter needs the ticket's repository,
+      # title and body — which are ON the ticket, and which the policy that
+      # triggered this cannot supply because a command's event payload is its
+      # ARGUMENTS, not its state. Without this, every ask would have to have
+      # its data re-passed through the command that fired it, so the same text
+      # would live in two places and could differ.
+      #
+      # ARGUMENTS WIN over state, because an argument is what THIS call said
+      # and state is what the record happens to hold.
+      def ask(ctx)
+        payload = held_state(ctx).merge(materialise(ctx.args))
+        answer  = adapter_for(ctx).public_send(Naming.snake(ctx.operation.hecks_name), **payload)
+        announce(ctx, ctx.operation.answers, ctx.args.merge(spread(answer)))
+      rescue StandardError => e
+        announce(ctx, ctx.operation.refuses, ctx.args.merge(refusal: { value: "#{e.class}: #{e.message}" }))
+      end
+
+      # THE ANSWER IS SPREAD, NOT NESTED — and that is what makes the loop
+      # close. A policy re-enters its target with the event payload VERBATIM;
+      # it cannot reach inside a key. So an answer tucked under `answered:`
+      # can be read by a human and by nothing else, and the command that
+      # should record the issue number never gets one.
+      #
+      # Spread, the adapter's own keys ARE the arguments of whatever command
+      # reacts to the answering event. Which is a real contract on the adapter
+      # — it must return what that command takes, in the shape the runtime
+      # coerces (`{ number: { value: 43 } }`, not `43`) — and naming it here
+      # is cheaper than a mapping layer nobody could see into.
+      #
+      # A non-Hash answer keeps the old shape: a port that returns a URL
+      # string has nothing to spread, and `answered:` is the honest word for
+      # a single unnamed value.
+      def spread(answer)
+        return { answered: answer } unless answer.is_a?(Hash)
+
+        answer.to_h { |key, value| [key.to_sym, deep_symbolize(value)] }
+      end
+
+      def deep_symbolize(value)
+        case value
+        when Hash  then value.to_h { |k, v| [k.to_sym, deep_symbolize(v)] }
+        when Array then value.map { |element| deep_symbolize(element) }
+        else value
+        end
+      end
+
+      # THE RECORD, IF THERE IS ONE. A record that does not exist yet is not
+      # an error here — the ask still goes, carrying only its arguments, and
+      # whatever the adapter makes of that is its own business. Refusing
+      # would put a second existence check behind the one `resolve_references`
+      # already performed.
+      def held_state(ctx)
+        ctx.instance ? Value.materialize(ctx.instance.state) : {}
+      rescue StandardError
+        {}
+      end
+
+      # THE PORT THIS OPERATION BELONGS TO, found by asking the aggregate
+      # rather than threading it through the call — the dispatcher already
+      # resolved it once to get here, and a second parameter carried purely so
+      # this method can read it would be a parameter every OTHER step ignores.
+      def port_name_for(ctx)
+        owning = ctx.aggregate.ports.find { |port| port.operations.any? { |op| op.equal?(ctx.operation) } }
+        owning&.name or raise WiringError,
+                              "#{ctx.operation.hecks_name} belongs to no port on #{ctx.aggregate.hecks_name}"
+      end
+
+      def adapter_for(ctx)
+        name = port_name_for(ctx)
+        implementations = @registry.adapters.values.select { |adapter| adapter.port == name }
+
+        case implementations.size
+        when 1 then Adapters.const_get(implementations.first.name).new
+        when 0 then raise WiringError, "no adapter implements the #{name} port — nothing can answer #{ctx.operation.hecks_name}"
+        else raise WiringError,
+                   "#{implementations.size} adapters implement the #{name} port " \
+                   "(#{implementations.map(&:name).sort.join(', ')}) — the runtime will not choose for you"
+        end
+      end
+
+      # A Value never crosses the boundary — an adapter is somebody else's
+      # code and should be handed plain data, the same reasoning `JsonDoor`
+      # gives for materialising before it hands anything to an HTTP caller.
+      def materialise(args) = Value.materialize(args)
+
+      def announce(ctx, event_name, payload)
+        event = Event.new(
+          name:        event_name,
+          aggregate:   "#{ctx.domain}::#{ctx.aggregate.hecks_name}",
+          id:          ctx.route.aggregate,
+          payload:     payload,
+          occurred_at: Time.now.utc.iso8601
+        )
+        @registry.event_log << event
+        [event]
+      end
+
+      # THE ONE PLACE THIS DIFFERS FROM CommandRules::Emission — there is no
+      # mutated instance to read an id off, because nothing was hydrated or
+      # saved. The record this event is ABOUT is named by whichever attribute
+      # is a reference to the owning aggregate (PortOperationBuilder#build
+      # already refused to build an operation with none), so its coerced
+      # value — already a plain id, never an object, per
+      # Value::Coercion#refuse_object_reference — is what stamps the event.
+      def emit(ctx)
+        ctx.operation.emits.map do |event_name|
+          event = Event.new(
+            name:        event_name,
+            aggregate:   "#{ctx.domain}::#{ctx.aggregate.hecks_name}",
+            id:          ctx.route.aggregate,
+            payload:     ctx.args,
+            occurred_at: Time.now.utc.iso8601
+          )
+          @registry.event_log << event.emit!
+          event
+        end
+      end
+    end
+  end
+end