hecks 0.2.0 → 0.3.0

data/lib/hecks/runtime/interpreting.rb

@@ -0,0 +1,69 @@
+require_relative "value"
+
+module Hecks
+  module Runtime
+    # What every stepwise interpreter shares: the traced step, and the
+    # coercion of a command's declared arguments. Two copies of each lived
+    # in CommandInterpreter and EntityInterpreter, where they could only
+    # ever drift.
+    module Interpreting
+      # Each including interpreter gets its own `trace` — set by a spec to
+      # observe dispatch order (Vocabulary::AggregateDispatchOrder and
+      # Vocabulary::EntityDispatchOrder in language/bluebook/vocabulary.bluebook);
+      # nil in production, always — one array push and a nil check per step
+      # is the entire cost of leaving this in.
+      def self.included(interpreter)
+        interpreter.singleton_class.attr_accessor :trace
+      end
+
+      private
+
+      # Logged AFTER the step's own work, so a step that wraps sub-steps logs
+      # itself once everything inside it has already logged — trace order is
+      # completion order, which is dispatch order.
+      def step(name)
+        result = yield
+        self.class.trace << name if self.class.trace
+        result
+      end
+
+      # DRIVES `DISPATCH_ORDER` (CommandInterpreter/EntityInterpreter, each
+      # mirroring its own Vocabulary::*DispatchOrder — vocabulary.bluebook,
+      # held equal to it by spec/vocabulary_conformance_spec.rb) by `send`ing
+      # each declared step name against the including interpreter's own
+      # `step_<name>` handler, in declared order. What used to be `call`'s own
+      # literal sequence of method calls is now DATA driving that sequence —
+      # tracing a real dispatch and comparing it to the declaration is
+      # tautological once `call` mechanically follows the declaration; a
+      # conditional step (assign_creation_attributes, advance_lifecycle) still
+      # has to guard ITSELF at the top of its own handler and skip tracing
+      # when it does not fire, rather than the caller branching around it —
+      # see CommandInterpreter#step_assign_creation_attributes.
+      def run_dispatch_order(order, ctx)
+        order.each { |name| send(:"step_#{name}", ctx) }
+      end
+
+      # Every declared attribute present in the payload passes the reference
+      # gate, then coercion — the same walk whether the command acts on an
+      # aggregate or on one of its entity's elements.
+      def coerce_declared_arguments(aggregate, command, args)
+        command.attributes.each_with_object(args.dup) do |attribute, normalized|
+          next unless normalized.key?(attribute.name)
+
+          Value.refuse_object_reference(command, attribute, normalized[attribute.name])
+          normalized[attribute.name] = Value.for_attribute(aggregate, attribute, normalized[attribute.name])
+        end
+      end
+
+      # Coercion only — CommandInterpreter's own refuse_unknown_arguments/
+      # refuse_absent_arguments are separate DISPATCH_ORDER steps now (the
+      # declared vocabulary lists all three as flat, sequential members, not
+      # one nesting the other two), and EntityInterpreter never had them here
+      # at all (an entity inherits its aggregate's own gate). One copy,
+      # shared, rather than the two identical ones that used to drift.
+      def normalize_args(aggregate, command, args)
+        coerce_declared_arguments(aggregate, command, args)
+      end
+    end
+  end
+end

data/lib/hecks/runtime/loader.rb

@@ -0,0 +1,143 @@
+require_relative "../facade/surface"
+require_relative "../ports/loading"
+require_relative "dispatcher"
+require_relative "remote_dispatcher"
+require_relative "era_check"
+require_relative "registry"
+
+module Hecks
+  module Runtime
+    class Loader
+      # `install_facade:` defaults on — every ordinary caller wants
+      # `Widget::Item.Add(...)` sugar. A caller that only ever dispatches
+      # by FQN string (`SmokeTest`, the one caller so far) can pass
+      # `false` to skip it: `Facade::Surface.install` puts a bare global
+      # Ruby constant on `Object` per domain AND per aggregate name, with
+      # no scoping and no cleanup hook, so a tool booting arbitrary
+      # throwaway domains under generic names ("Widget", "Item", "Tag")
+      # would otherwise leak those names into the rest of the process —
+      # measured, not hypothetical: this exact leak once made an
+      # unrelated `dsl_spec.rb` example resolve a bare `Widget` constant
+      # to a stale smoke-test facade from a deleted temp directory instead
+      # of raising, corrupting that spec's own unrelated build. Skipping
+      # the install is safe because nothing downstream of a raw
+      # `Dispatcher` needs the sugar — `Dispatcher#dispatch`/`#query` work
+      # identically either way.
+      # `environment:` — see Adapters::Folder#load_domain's own comment
+      # for the mechanism. hecks never reads ENV itself (every other
+      # env-var lookup in this codebase lives in app-owned .world/
+      # .hecksagon files, never library internals) — a caller resolves
+      # its own env var name and passes the resulting string straight
+      # through, e.g. `Hecks.boot(path, environment:
+      # ENV.fetch("MYAPP_ENV", "development"))`.
+      def self.boot(path, shared: nil, install_facade: true, environment: nil)
+        loading   = Ports::Loading.bootstrap
+        directory = loading.bluebook_directory(path)
+        root      = loading.shared_root(shared, directory)
+        registry  = Registry.new(root: File.dirname(directory))
+
+        Hecks.with_registry(registry) do
+          loading.load_library
+          loading.load_project(root)
+          loading.load_domain(directory, environment: environment)
+        end
+
+        # The era gate runs BEFORE verify! builds repositories: minting an
+        # era (Postgres) must have created its partition and head views
+        # before any adapter opens them, and a refused era must refuse
+        # before any adapter touches data.
+        EraCheck.check!(registry, directory)
+        registry.verify!
+        # AFTER verify! (conservative — any wiring error surfaces first,
+        # not strictly required since resolution only needs the
+        # hecksagon binds, already loaded), BEFORE the dispatcher is
+        # built — repopulates `saga_instances` from whatever durable
+        # store each domain's own adapter answers with (§2-§4), so a
+        # process manager mid-flight at the last shutdown/crash/cold-
+        # start doesn't start this boot looking like it never began.
+        registry.rehydrate_sagas!
+        dispatcher = dispatcher_for(registry)
+        install_facade ? bind_runtime(dispatcher) : dispatcher
+      end
+
+      # THE EXPLICIT-FILE FORM — `paths` names the exact bluebook/hecksagon/
+      # world files to boot, in place, wherever they actually live. `boot`
+      # above only ever takes a directory and globs it; that is the right
+      # shape for a real deployment (`examples/banking`, a domain someone
+      # `cd`s into), and the wrong one for a caller that wants to declare a
+      # narrow, explicit scope and have it booted exactly as declared — a
+      # `.behaviors` file's own `loads` line is the motivating caller
+      # (`Hecks::Behaviors`), but this carries no behaviors-specific
+      # logic and is not gated behind requiring that module.
+      #
+      # NO COPYING, NO TEMP DIRECTORY. A prior port of this same idea
+      # (vendored into a downstream consumer, read before writing this)
+      # scoped a per-test boot by copying files into `Dir.mktmpdir` — which
+      # destroys real relative paths, and worse, makes a `persisted_by`
+      # path resolve against the TEMP copy's root instead of the project's
+      # own (confirmed there: a file adapter kept reading and writing the
+      # same deterministic tmp copy across an entire session, because
+      # `Hecks.boot`'s own `root` is always `File.dirname` of whatever
+      # directory it was handed). `directory` here is `File.dirname` of the
+      # FIRST real path in `paths` — genuinely on disk, not a copy — so
+      # every downstream path (`EraCheck`, `persisted_by`, `shared_root`)
+      # resolves exactly as an ordinary directory boot's would.
+      def self.boot_files(paths, shared: nil, install_facade: true, environment: nil)
+        loading   = Ports::Loading.bootstrap
+        files     = Array(paths).map { |path| File.expand_path(path) }
+        directory = File.dirname(files.first)
+        root      = loading.shared_root(shared, directory)
+        registry  = Registry.new(root: File.dirname(directory))
+
+        Hecks.with_registry(registry) do
+          loading.load_library
+          loading.load_project(root)
+          loading.load_selected(files, environment: environment)
+        end
+
+        EraCheck.check!(registry, directory)
+        registry.verify!
+        registry.rehydrate_sagas!
+        dispatcher = dispatcher_for(registry)
+        install_facade ? bind_runtime(dispatcher) : dispatcher
+      end
+
+      # `RemoteDispatcher` for a domain routed through Lambda,
+      # `Dispatcher` otherwise — the ONE place this decision gets
+      # made, so everything built on top (`Handle`, `AggregateDoor`,
+      # `Facade::Surface`) never has to know which class it's holding.
+      # `registry.bluebooks.keys.first` is the just-booted domain's own
+      # name (insertion order — the target's own bluebook loads before
+      # any `uses_framework` chapter, `bin/project_rust`'s own header
+      # draws the identical distinction), not a directory basename.
+      #
+      # `dispatched_by("Lambda")` is its OWN, EXPLICIT verb — NOT
+      # inferred from `deployed_to("AwsLambda")`'s mere presence. Both
+      # Banking's and Embryonaut's `.world` files already declare
+      # `deployed_to("AwsLambda")` (it only means "a deploy target
+      # exists"), so treating that alone as "boot this domain against
+      # Lambda" would have silently rerouted Banking's every local
+      # boot — every spec, every `bin/console` session — the moment
+      # this landed. A domain opts in explicitly, the same way
+      # `persisted_by("PostgresEra")` is never inferred from anything
+      # else either.
+      def self.dispatcher_for(registry)
+        domain = registry.bluebooks.keys.first
+        settings = registry.world(domain)&.for_verb("dispatched_by") || {}
+        return Dispatcher.new(registry) unless settings[:adapter] == "Lambda"
+
+        RemoteDispatcher.new(registry, region: settings.fetch(:region, "us-east-1"))
+      end
+
+      # THE DOOR IS INSTALLED HERE, NOT STAMPED. This used to write the
+      # dispatcher onto every aggregate's class (`ruby_class.runtime =`) — the
+      # class-level global that made two boots in one process share one
+      # name. The facade's modules close over THIS dispatcher instead, so the
+      # binding lives in the surface a boot installs, not on anything shared.
+      def self.bind_runtime(dispatcher)
+        Facade::Surface.install(dispatcher)
+        dispatcher
+      end
+    end
+  end
+end

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