hecks 2.8.0 → 3.0.0

data/lib/hecks/runtime/dispatcher.rb

@@ -1,5 +1,6 @@
 require_relative "errors"
 require_relative "refusal_wording"
+require_relative "reaction_outcome"
 require_relative "caller"
 require_relative "invocation"
 require_relative "command_rules"
@@ -14,36 +15,49 @@ require_relative "../naming"
 
 module Hecks
   module Runtime
-    # The runtime's single dispatch entry point for one booted registry:
-    # routes a "Domain::Aggregate.Command"-shaped verb to the right
-    # sub-interpreter (command, entity, port operation, query, read
-    # model), then runs every policy and saga reaction the resulting
-    # events trigger. Also the door reactions dispatch back through
-    # (#reenter), and the one place reaction-cascade depth is tracked, to
-    # keep a policy/saga loop from re-triggering itself without bound.
+    # Routes a "Domain::Aggregate.Command" verb to its interpreter, then runs the policy
+    # and saga reactions its events trigger; tracks reaction depth to bound cascades.
     class Dispatcher
       MAX_REACTION_DEPTH = 5
 
-      Result = Struct.new(:verb, :instance, :events, :execution_plan, :persistence_outcome, keyword_init: true) do
-        # Reads the identity of the record the dispatch settled on.
+      Result = Struct.new(:verb, :instance, :events, :execution_plan, :persistence_outcome,
+                          :refused_reactions, :blocking_reactions, :reaction_defects,
+                          keyword_init: true) do
+        # Lists the policy reactions this dispatch caused that the domain refused.
+        #
+        # A policy's trigger that a `given` or invariant refuses does not undo the command that
+        # fired it, which has already persisted, so the outcome above stays a success. The
+        # refusal is recorded here instead of vanishing into the reaction log.
+        #
+        # @return [Array<Hash{Symbol => Object}>] one `{ policy:, trigger:, reason: }` per refused
+        #   reaction, oldest first; empty when every reaction was delivered
+        def refused_reactions = self[:refused_reactions] || []
+
+        # Lists the refused reactions that block the run, as opposed to a benign non-match.
+        #
+        # See `ReactionOutcome`: a refusal is benign when a sibling reaction to the same event
+        # delivered another command on the same aggregate. `--wait` exits 1 on any that remain.
+        #
+        # @return [Array<Hash{Symbol => Object}>] the subset of `refused_reactions` that blocks
+        def blocking_reactions = self[:blocking_reactions] || []
+
+        # Lists the reactions that crashed, as opposed to being refused by the domain.
         #
-        # `instance` is nil for a port operation dispatched by verb (below)
-        # — nothing was hydrated or saved, the same reason
-        # `PortOperationInterpreter#emit`'s own comment gives for sourcing
-        # `id:` off the operation's reference attribute instead. `&.`, not
-        # a raised error: a caller that dispatches a port verb and then
-        # asks this Result for `.id`/`.state` made a category error the
-        # domain itself already told it about (there is no record here),
-        # not a crash-worthy one.
+        # A crash is warned and never re-raised, since the emitting command has persisted; it is
+        # recorded here so `--wait` can fail on a chain that stopped halfway.
         #
-        # @return [String, nil] the record's identity; nil for a port operation, which
-        #   hydrates no record
+        # @return [Array<Hash{Symbol => Object}>] `{ policy:, trigger:, reason:, error_class: }`
+        #   per crashed reaction; empty when none crashed
+        def reaction_defects = self[:reaction_defects] || []
+
+        # Reads the identity of the record the dispatch settled on.
+        #
+        # @return [String, nil] the record's identity; nil for a port operation (no record)
         def id    = instance&.id
 
-        # Reads the settled record's attributes as one Hash, for the same nil-safe reason as `id`.
+        # Reads the settled record's attributes as one Hash.
         #
-        # @return [Hash{Symbol => Object}, nil] the record's state with `:id` merged in
-        #   last; nil for a port operation, which hydrates no record
+        # @return [Hash{Symbol => Object}, nil] the record's state; nil for a port operation
         def state = instance&.to_h
 
         def to_s
@@ -56,8 +70,7 @@ module Hecks
 
       attr_reader :registry
 
-      # @param registry [Runtime::Registry] the booted registry every interpreter reads; its
-      #   outbox is attached to this dispatcher's policy and saga interpreters
+      # @param registry [Runtime::Registry] the booted registry every interpreter reads
       def initialize(registry)
         @registry = registry
         rules     = CommandRules.new(registry)
@@ -68,108 +81,72 @@ module Hecks
         @read_models = ReadModelInterpreter.new(registry)
         @policies = PolicyInterpreter.new(registry, door: self)
         @sagas    = SagaInterpreter.new(registry, door: self)
-        # The relay is the registry's, not this dispatcher's — the
-        # interpreters enqueue through `@registry.outbox` from inside
-        # the save transaction, and this dispatcher drains through the
-        # same object, so there is exactly one relay per registry no
-        # matter how many dispatchers front it. What it borrows from
-        # here is the pair of interpreters a consumer runs through.
+        # One relay per registry: interpreters enqueue through it inside the save transaction.
         @registry.outbox.attach(policies: @policies, sagas: @sagas)
       end
 
-      # Exposes the registry's outbox relay, the object this dispatcher drains reactions through.
+      # Exposes the registry's outbox relay, through which this dispatcher drains reactions.
       #
-      # `runtime.outbox.rows`, `.rows(status: "claimed")`, `.redrive!`,
-      # `.log` — see `Runtime::Outbox`.
-      #
-      # @return [Runtime::Outbox::Relay] the registry's one relay, shared by every dispatcher
-      #   fronting that registry
+      # @return [Runtime::Outbox::Relay] the registry's one relay
       def outbox = @registry.outbox
 
-      # Exposes every event emitted through this registry since boot or the last reset.
+      # Exposes every event emitted through this registry, oldest first.
       #
-      # @return [Array<Runtime::Event>] the registry's live event log, oldest first
+      # @return [Array<Runtime::Event>]
       def events = @registry.event_log
 
-      # Exposes one record per policy reaction that was delivered, refused or left undelivered.
+      # Exposes one record per policy reaction delivered, refused or left undelivered.
       #
-      # @return [Array<Hash{Symbol => Object}>] the registry's live reaction log, oldest first
+      # @return [Array<Hash{Symbol => Object}>]
       def reactions = @registry.reaction_log
 
       # Exposes one record per process-manager step: a start, an advance, a delivery, a refusal.
       #
-      # @return [Array<Hash{Symbol => Object}>] the registry's live saga log, oldest first
+      # @return [Array<Hash{Symbol => Object}>]
       def sagas = @registry.saga_log
 
-      # Exposes the raw inputs each saga dispatch bound its arguments from, a Ruby-only log.
+      # Exposes the raw inputs each saga dispatch bound its arguments from (Ruby-only).
       #
-      # @return [Array<Hash{Symbol => Object}>] the registry's live saga dispatch log, oldest first
+      # @return [Array<Hash{Symbol => Object}>]
       def saga_dispatches = @registry.saga_dispatch_log
 
-      # Exposes the raw inputs each policy trigger bound its arguments from, a Ruby-only log.
+      # Exposes the raw inputs each policy trigger bound its arguments from (Ruby-only).
       #
-      # @return [Array<Hash{Symbol => Object}>] the registry's live policy dispatch log, with
-      #   keys `:policy`, `:on`, `:payload`, `:with_spec` and `:args`
+      # @return [Array<Hash{Symbol => Object}>] entries keyed `:policy`, `:on`, `:payload`,
+      #   `:with_spec` and `:args`
       def policy_dispatches = @registry.policy_dispatch_log
 
       # Lists every verb the loaded bluebooks declare.
       #
-      # @return [Array<String>] the verbs of every loaded bluebook, sorted
+      # @return [Array<String>] sorted
       def verbs = @registry.verbs
 
-      # Runs one command, entity command or port operation, then every policy and saga reaction
-      # its events are owed.
-      #
-      # 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.
+      # Runs one command, entity command or port operation, then the reactions its events owe.
       #
-      # @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)
-      # @param saga_correlation [Hash, nil] correlation head => value, stamped on every
-      #   emitted event when a saga leg causes this dispatch; nil otherwise
-      # @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,
-      #   aggregate, command, entity or port operation that is not declared
-      # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when the domain refuses
-      #   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
+      # @param verb [String] `"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 `:entity`/`:entities`
+      # @param with [Hash, nil] the command's facts, keyed by argument name
+      # @param saga_correlation [Hash, nil] stamped on emitted events when a saga leg dispatches
+      # @return [Runtime::Dispatcher::Result] the instance is nil for a port operation
+      # @raise [Runtime::UnknownVerb] if the verb is malformed or names something undeclared
+      # @raise [StandardError] a `Runtime::DOMAIN_REFUSALS` class when the domain refuses
+      # @raise [Runtime::StaleWrite] if concurrent writers win every retry
       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: 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, as it did).
-      # Framework code that replays data calls this; application code
-      # calls `dispatch(verb, to:, with:)`.
+      # The wire form: Symbol keys `:to`, `:with` and `:saga_correlation` are lifted out as
+      # the keywords of `dispatch`; every other key, including a String "to", is a fact.
       #
       # @param verb [String] the fully qualified verb, in any shape `dispatch` accepts
-      # @param args [Hash] the facts, plus optional Symbol keys `:to`, `:with` and
-      #   `:saga_correlation`, read as `dispatch`'s keywords of the same names; not mutated
+      # @param args [Hash] the facts plus the optional Symbol keys above; not mutated
       # @return [Runtime::Dispatcher::Result] the same result `dispatch` returns
-      # @raise [Runtime::UnknownVerb] if the verb is not fully qualified, or names a domain,
-      #   aggregate, command, entity or port operation that is not declared
-      # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when the domain refuses
-      #   the call
-      # @raise [Runtime::StaleWrite] if concurrent writers beat this one through every retry
-      # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
+      # @raise [Runtime::UnknownVerb] if the verb is malformed or names something undeclared
+      # @raise [StandardError] a `Runtime::DOMAIN_REFUSALS` class when the domain refuses
       def dispatch_flat(verb, args = {})
         facts = args.dup
         to = facts.delete(:to)
@@ -179,6 +156,14 @@ module Hecks
       end
 
       def dispatch_invocation(verb, to:, with:, saga_correlation:, flat:)
+        @registry.collecting_reactions do |reactions|
+          dispatch_collecting(verb, reactions, to: to, with: with, saga_correlation: saga_correlation, flat: flat)
+        end
+      end
+      private :dispatch_invocation
+
+      # One dispatch, with `reactions` receiving every reaction its events cause.
+      def dispatch_collecting(verb, reactions, to:, with:, saga_correlation:, flat:)
         domain, aggregate_name, command_name = parse(verb)
         aggregate = resolve_aggregate(domain, aggregate_name, verb)
 
@@ -186,17 +171,8 @@ module Hecks
           if command_name.include?(".")
             head, sub = command_name.split(".", 2)
             port = aggregate.port(head)
-            # A port operation, reached by the same verb shape an entity
-            # command already uses ("Domain::Aggregate.Head.Rest") — ports
-            # are checked first, so an aggregate that ever declared both a
-            # port and an entity of the same name would resolve to the
-            # port; no domain in this corpus does, and `dispatch_port`'s
-            # own header already named this as an open wire-spelling
-            # question this resolves, not silently avoids. No `instance`
-            # comes back — nothing is hydrated or saved by a port
-            # operation (`PortOperationInterpreter`'s own header) — so
-            # `Result#id`/`#state` are nil-safe (above) for exactly this
-            # path.
+            # Ports are checked before entities, so a port wins a name an entity also declares.
+            # No instance comes back: a port operation hydrates and saves nothing.
             if port
               operation = port.operation(sub) ||
                           raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "port_no_operation",
@@ -218,37 +194,31 @@ module Hecks
             @commands.call(domain, aggregate, command, invocation, saga_correlation)
           end
 
-        # Correlation is set when each event is constructed, not merged on
-        # here — it is part of the transaction, known from this method's
-        # own argument before a single event exists. Stamping it onto
-        # already-emitted events would keep an event mutable after it had
-        # happened.
-        #
-        # The ordering that depends on it holds for the same reason:
-        # `SagaInterpreter#advance` runs on this domain's `announced`
-        # events within this very call, and finds the correlation already
-        # there because it was never absent.
+        # Correlation is stamped as each event is built, so emitted events are never mutated.
 
         react(announced, domain, aggregate, outbox_rows)
 
         Result.new(verb: verb, instance: instance, events: announced,
-                   execution_plan: execution_plan, persistence_outcome: persistence_outcome)
+                   execution_plan: execution_plan, persistence_outcome: persistence_outcome,
+                   refused_reactions: refused_from(reactions),
+                   blocking_reactions: ReactionOutcome.blocking(reactions, event_of: @registry.method(:reaction_event)),
+                   reaction_defects: ReactionOutcome.defects(reactions))
       end
+      private :dispatch_collecting
 
-      # **The one body both doors run** — `dispatch` (keywords) and
-      # `dispatch_flat` (one Hash) differ only in how the call's parts are
-      # spelled, never in what happens next.
-      private :dispatch_invocation
+      # The reactions among `logged` that the domain refused, as plain facts.
+      #
+      # A crash in a reaction is a defect, not a refusal, and is warned where it happens.
+      def refused_from(logged)
+        logged.select { |entry| entry[:delivered] == false && !entry[:defect] }
+              .map { |entry| entry.slice(:policy, :trigger, :reason) }
+      end
+      private :refused_from
 
-      # **Everything owed because `announced` committed** — policies first,
-      # then sagas, the order this method always ran them in. The
-      # command/entity interpreters hand back the outbox rows they
-      # enqueued inside the save transaction (`Interpreting#
-      # run_dispatch_order`); a port operation saves nothing, so its
-      # rows are enqueued here, after the fact (`:enqueue`) — durable
-      # still, just not transactional with anything, because there is
-      # nothing for them to be transactional with. `nil` rows mean the
-      # repository has no outbox: react directly, exactly as before.
+      # Runs the policy and saga reactions owed because `announced` committed.
+      #
+      # A port operation saves nothing, so its outbox rows are enqueued here (`:enqueue`);
+      # nil rows mean the repository has no outbox and reactions run directly.
       def react(announced, domain, aggregate, outbox_rows)
         return if announced.empty?
 
@@ -260,38 +230,16 @@ module Hecks
 
       # Answers whether a command would succeed right now, without saving, emitting or reacting.
       #
-      # "If this were dispatched right now, would it succeed" — the same
-      # pipeline #dispatch itself runs (arguments coerced, givens checked,
-      # mutations applied in memory, ensures checked against the settled
-      # result), except `step_save`/`step_emit` never run, and neither do
-      # policies or sagas afterward: nothing here is committed, so nothing
-      # should react to it. Built for exactly the shape a whole-board
-      # postcondition needs to be tested against (a downstream project's
-      # own chess domain, checking "does this move leave my own king in
-      # check" — the alternative was dispatching a real, unrelated piece's
-      # own move purely to trigger the check, which then had to avoid
-      # interfering with the very position being tested).
-      #
-      # Raises the same refusals #dispatch does — a DomainRefusal
-      # subclass propagates normally, so a caller checking "would this be
-      # legal" writes the identical rescue clause a real dispatch already
-      # needs; this returns `true` only when nothing was refused.
-      #
-      # **Never a port verb** — `PortOperationInterpreter`'s own side effects
-      # (an external gateway call, say) have no meaningful in-memory-only
-      # form, so this refuses one outright rather than silently running
-      # it for real, which "dry" would otherwise quietly lie about.
+      # Runs the dispatch pipeline in memory only; refusals raise exactly as `dispatch` raises
+      # them. A port verb is refused: its side effects have no in-memory form.
       #
       # @param verb [String] the fully qualified aggregate or entity command verb
-      # @param args [Hash{Symbol => Object}] the command's facts as flat keywords; a key named
-      #   `to` or `with` is an ordinary fact here, never routing (BUG#131)
-      # @return [true] whenever nothing refused; a refusal is raised, never returned as false
-      # @raise [Runtime::WiringError] if the verb names a port operation, or the aggregate's
-      #   repository cannot be resolved
-      # @raise [Runtime::UnknownVerb] if the verb is not fully qualified, or names a domain,
-      #   aggregate, command or entity that is not declared
-      # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` that the real dispatch
-      #   would raise
+      # @param args [Hash{Symbol => Object}] the facts as flat keywords; `to` and `with` are
+      #   ordinary facts here, never routing
+      # @return [true] whenever nothing refused
+      # @raise [Runtime::WiringError] if the verb names a port operation
+      # @raise [Runtime::UnknownVerb] if the verb is malformed or names something undeclared
+      # @raise [StandardError] any `Runtime::DOMAIN_REFUSALS` class the real dispatch would raise
       def dry_run?(verb, **args)
         domain, aggregate_name, command_name = parse(verb)
         aggregate = resolve_aggregate(domain, aggregate_name, verb)
@@ -304,8 +252,7 @@ module Hecks
                   "only for aggregate and entity commands"
           end
 
-          # `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.
+          # `to:`/`with:` are not keywords here; a key named either is an ordinary fact.
           resolution = nil
           invocation = Invocation.from_call(verb, to: nil, with: nil, flat: args, receiver: :entity) do
             (resolution = EntityInterpreter::Resolution.of(aggregate, command_name)).command
@@ -320,36 +267,18 @@ module Hecks
         true
       end
 
-      # Runs one port operation named by its parts, then the reactions its events are owed.
+      # Runs one port operation named by its parts, then the reactions its events owe.
       #
-      # The door an adapter outside the bluebook calls through — never the
-      # domain itself. `port_name`/`operation_name` are separate arguments
-      # rather than one packed verb string on purpose: there is no established
-      # wire spelling for "domain, aggregate, port, operation" yet, and
-      # inventing one is a bigger decision than this call needs to make.
+      # The door for an adapter outside the bluebook; the parts are separate arguments because
+      # no wire spelling for a packed port verb exists.
       #
-      # No adapter-to-port binding lookup happens here — that is
-      # `Hecks.adapter`'s existing job (unchanged by this), and wiring "which
-      # adapter may call this port" through is the next piece, not this one.
-      #
-      # @param domain [String, Symbol] name of the domain the aggregate belongs to
-      # @param aggregate_name [String, Symbol] name of the aggregate that declares the port
-      # @param port_name [String] name of the port, as the aggregate declares it
-      # @param operation_name [String] name of the operation on that port
-      # @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 to [String, Hash, nil] the receiver; when nil it is read from the facts
       # @param with [Hash, nil] the operation's facts, keyed by argument name
-      # @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
-      # @raise [Runtime::UnknownVerb] if the domain, aggregate, port or operation is not declared
-      # @raise [Runtime::TypeMismatch] if no receiving identity can be found, or `to:`/`with:`
-      #   is malformed
-      # @raise [Runtime::NotFound] if the receiving aggregate record does not exist
-      # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
+      # @param flat [Hash] the `dispatch_flat` wire form, for an adapter holding a decoded webhook
+      # @return [Array<Runtime::Event>] the events the operation announced
+      # @raise [Runtime::UnknownVerb] if the domain, aggregate, port or operation is undeclared
+      # @raise [Runtime::TypeMismatch] if no receiving identity is found, or `to:`/`with:` is bad
+      # @raise [Runtime::NotFound] if the receiving record does not exist
       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) ||
@@ -369,22 +298,16 @@ module Hecks
 
       # Answers a declared query: an aggregate query, an entity query, or a read model.
       #
-      # The verb's shape picks the interpreter. `"Domain.ReadModel"` — no `::` before the
-      # dot — is a read model; `"Domain::Aggregate.Query"` is an aggregate query, and
-      # `"Domain::Aggregate.Entity.Query"` an entity query.
+      # `"Domain.ReadModel"` (no `::`) is a read model; `"Domain::Aggregate.Query"` and
+      # `"Domain::Aggregate.Entity.Query"` are aggregate and entity queries.
       #
       # @param verb [String, Symbol] the query's verb, in one of the three shapes above
       # @param args [Hash{Symbol => Object}] the query's declared arguments
-      # @return [Array<Hash>] for an aggregate query, one deep-frozen Hash per matching record,
-      #   its state with `:id` merged in last; for an entity query, one Hash per matching
-      #   element with the parent's reference key merged in first; for a read model, a
+      # @return [Array<Hash>] one Hash per matching record or element; a read model returns a
       #   one-element Array holding a Hash of head name to projected rows
-      # @raise [Runtime::UnknownVerb] if the verb is not fully qualified, or names a domain,
-      #   aggregate, entity, query or read model that is not declared
+      # @raise [Runtime::UnknownVerb] if the verb is malformed or names something undeclared
       # @raise [Runtime::NotFound] if a read model's root reference names no record
       # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its declared type
-      # @raise [KeyError] if a rooted read model is asked without its reference argument
-      # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
       def query(verb, **args)
         domain, query_name = verb.to_s.split(".", 2)
         if query_name && !domain.include?("::")
@@ -404,20 +327,14 @@ module Hecks
 
       # Answers an aggregate or entity query through the reference interpreter alone.
       #
-      # The same ask as `#query`, never answered by the bound adapter's
-      # native hook. Read models have no reference twin, so only the
-      # `"Domain::Aggregate.Query"` forms answer here; the fuzzer's
-      # query oracle diffs this against `#query`'s answer.
+      # Never answered by the bound adapter's native hook; the fuzzer's query oracle diffs it
+      # against `#query`. Read models have no reference twin.
       #
-      # @param verb [String] the fully qualified query verb, `"Domain::Aggregate.Query"` or
-      #   `"Domain::Aggregate.Entity.Query"`
+      # @param verb [String] `"Domain::Aggregate.Query"` or `"Domain::Aggregate.Entity.Query"`
       # @param args [Hash{Symbol => Object}] the query's declared arguments
-      # @return [Array<Hash>] one Hash per matching record, its state with `:id` merged in
-      #   last; for an entity query, one Hash per matching element
-      # @raise [Runtime::UnknownVerb] if the verb is not fully qualified, or names a domain,
-      #   aggregate, entity or query that is not declared
+      # @return [Array<Hash>] one Hash per matching record or element
+      # @raise [Runtime::UnknownVerb] if the verb is malformed or names something undeclared
       # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its declared type
-      # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
       def reference_query(verb, **args)
         domain, aggregate_name, query_name = parse(verb)
         aggregate = resolve_aggregate(domain, aggregate_name, verb)
@@ -425,43 +342,18 @@ module Hecks
         @queries.reference_call(domain, aggregate, query_name, args)
       end
 
-      # Dispatches a reaction's command one level deeper in the cascade, as the system rather
-      # than as the triggering caller.
-      #
-      # A reaction is the system acting, not the caller who happened to be
-      # on the stack when the triggering command ran — the ambient caller
-      # is cleared for the reaction's own dispatch, so a triggering
-      # caller's role can neither satisfy nor block a reaction command it
-      # has nothing to do with (Runtime::Caller.without).
-      #
-      # `Thread.current[:hecks_reaction_depth]`, not a plain ivar — this
-      # `Dispatcher` instance is a single object shared by every thread
-      # dispatching through it (a Puma worker pool, say), so a plain ivar
-      # here is exactly the known Puma-concurrency bug class: two
-      # concurrent top-level dispatches on different threads would
-      # increment/decrement the same counter, letting one thread's nested
-      # reaction depth leak into another thread's unrelated dispatch. A
-      # `Mutex` is not the answer either — a reaction cascade re-enters
-      # `reenter` on the same thread (see `SagaInterpreter#advance_saga`'s
-      # own comment on why a non-reentrant `Mutex` can't guard this).
-      # `Thread.current`-backed, saved/restored around the call with a
-      # plain local + `ensure`, is the same idiom `Runtime::Caller`
-      # (`caller.rb`) already established for exactly this shape of
-      # per-thread ambient state.
+      # Dispatches a reaction's command one level deeper in the cascade, as the system.
       #
-      # The depth is not checked here: a reacting interpreter asks
-      # `reaction_depth_reached?` first and records an undelivered reaction
-      # instead of calling this.
+      # The ambient caller is cleared (Runtime::Caller.without) so the triggering caller's role
+      # neither satisfies nor blocks the reaction. Depth lives in `Thread.current`, not an ivar
+      # or Mutex: the dispatcher is shared across threads and cascades re-enter on one thread.
+      # The depth limit is checked by the reacting interpreter, not here.
       #
       # @param verb [String] the fully qualified verb of the reaction's target command
-      # @param saga_correlation [Hash{String => Object}, nil] correlation head => value when a
-      #   saga leg dispatches; nil for a policy
-      # @param args [Hash{Symbol => Object}] the flat facts, read exactly as `dispatch_flat`
-      #   reads them, so `:to` and `:with` keys route rather than count as facts
-      # @return [Runtime::Dispatcher::Result] the result of the nested dispatch
-      # @raise [Runtime::UnknownVerb] if the verb names nothing declared
-      # @raise [StandardError] any class in `Runtime::DOMAIN_REFUSALS` when the target
-      #   refuses; the policy and saga interpreters rescue these as recorded outcomes
+      # @param saga_correlation [Hash{String => Object}, nil] set when a saga leg dispatches
+      # @param args [Hash{Symbol => Object}] flat facts, read as `dispatch_flat` reads them
+      # @return [Runtime::Dispatcher::Result] the nested dispatch's result
+      # @raise [StandardError] any `Runtime::DOMAIN_REFUSALS` class; interpreters rescue these
       def reenter(verb, saga_correlation: nil, **args)
         depth = Thread.current[:hecks_reaction_depth].to_i
         Thread.current[:hecks_reaction_depth] = depth + 1
@@ -472,13 +364,12 @@ module Hecks
 
       # Answers whether the calling thread's reaction cascade is as deep as it may go.
       #
-      # @return [Boolean] true once this thread's nested `reenter` calls number
-      #   `MAX_REACTION_DEPTH` or more; other threads' cascades are not counted
+      # @return [Boolean] true once nested `reenter` calls on this thread reach the limit
       def reaction_depth_reached? = Thread.current[:hecks_reaction_depth].to_i >= MAX_REACTION_DEPTH
 
-      # Reads the cascade limit, for the reason an interpreter records when it declines to react.
+      # Reads the cascade limit an interpreter records when it declines to react.
       #
-      # @return [Integer] `MAX_REACTION_DEPTH`, the number of nested reactions allowed
+      # @return [Integer] `MAX_REACTION_DEPTH`
       def max_reaction_depth      = MAX_REACTION_DEPTH
 
       private