hecks 2.7.0 → 2.9.0

data/lib/hecks/runtime/query_interpreter.rb

@@ -11,36 +11,22 @@ require_relative "value"
 
 module Hecks
   module Runtime
-    # Answers one declared aggregate or entity query against a
-    # repository: prefers a native adapter hook (Ports::Query.execute)
-    # when the store can answer directly, falling back to interpreting
-    # wheres/order_by/limit/offset over every loaded record itself.
-    # #reference_call/#reference_interpret are a separate, deliberately
-    # naive re-implementation of the same evaluation, used only as the
-    # fuzzer's oracle to catch divergence between adapters and this
-    # interpreter's own native path.
+    # Answers one declared aggregate or entity query against a repository, using a
+    # native adapter hook when the store has one and interpreting the query otherwise.
     class QueryInterpreter
       attr_reader :registry
 
-      # @param registry [Runtime::Registry] the booted registry queries are answered
-      #   against
       def initialize(registry)
         @registry = registry
       end
 
       # Answers one declared aggregate or entity query, preferring a native adapter
-      # hook and falling back to interpreting the query over every loaded record.
+      # hook and falling back to interpreting it over every loaded record.
       #
-      # @param domain [String, Symbol] the domain `aggregate` belongs to
-      # @param aggregate [Bluebook::Aggregate] the aggregate the query is declared on
-      # @param query_name [String] the query's declared name, or an entity query's
-      #   dotted `"Entity.Query"` name
-      # @param args [Hash{Symbol => Object}] the query's declared arguments
-      # @return [Array<Hash>] one frozen Hash per matching record, its state with
-      #   `:id` merged in last
+      # @param query_name [String] a declared name, or an entity query's `"Entity.Query"`
+      # @return [Array<Hash>] one frozen Hash per matching record, `:id` merged in last
       # @raise [Runtime::UnknownVerb] if `query_name` names no declared query
-      # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its
-      #   declared type
+      # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its type
       # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
       def call(domain, aggregate, query_name, args)
         return entity_rows(domain, aggregate, query_name, args) if query_name.include?(".")
@@ -48,67 +34,33 @@ module Hecks
         declared = declared_query(aggregate, query_name)
         args = normalize_args(aggregate, declared, args)
         declared = TenantScope.apply(declared, args)
-        # After TenantScope, so its synthetic clause is already present
-        # in `.wheres` and rides through as an ordinary local clause on
-        # the outer query. It does not reach the hop's own inner
-        # sub-query against the target aggregate — a hop's target may
-        # not even declare the same tenant boundary, and propagating one
-        # aggregate's tenant scope onto an unrelated aggregate's own
-        # query is a real design question of its own, not answered here.
+        # Applied after TenantScope so its tenant clause rides through as an ordinary
+        # local clause; it is deliberately not propagated into the hop's inner query.
         declared = ReferenceHop.apply(declared, args, registry: @registry, domain: domain, aggregate: aggregate)
 
         repository = @registry.repository(domain, aggregate)
-        # `registry:` is threaded through so a `none_in_state` where-clause
-        # can look its target aggregate up — see
-        # QuerySpecification::Common::Comparison#none_in_state? for the
-        # comparator itself, and for why an ordinary aggregate-level
-        # Memory query needs the registry passed explicitly rather than
-        # closing over an instance variable.
+        # `registry:` lets a `none_in_state` where-clause look up its target aggregate.
         if (native = Ports::Query.execute(repository, declared, args,
                                           context: { domain: domain, aggregate: aggregate, registry: @registry }))
           records = native
-          # `record.state.merge(id: record.id)` — id last, not first. See
-          # Instance#to_h's own comment: an aggregate free to declare its
-          # own attribute literally named `id` has that attribute's own
-          # wrapped value sitting in `record.state[:id]` already; merging
-          # it over a `{id:}.merge(state)` would let it silently
-          # clobber the correct bare identity this row is supposed to
-          # carry.
-          # A query row is an answer, not a handle. Mutating one edits
-          # nobody's state and silently disagrees with the store.
+          # `id` merges last so an aggregate attribute named `id` cannot clobber the
+          # bare identity (see Instance#to_h). Rows are frozen: a mutated row would
+          # edit nobody's state and disagree with the store.
           return Freezer.deep(records.map { |record| record.state.merge(id: record.id) })
         end
 
         Freezer.deep(interpret(repository.all, declared, args, domain: domain))
       end
 
-      # The reference answer — this interpreter's own evaluation, never an
-      # adapter's native hook. The fuzzer's query oracle replays every
-      # generated ask through both paths and treats a difference as a
-      # finding: the differential gate the retired cross-runtime harness
-      # should always have been, aimed where the divergence actually
-      # lives — between the engines inside this one runtime.
+      # The reference answer: this interpreter's own evaluation, never a native hook.
+      # The fuzzer's query oracle diffs it against #call.
       #
-      # A hop clause is answered here by its own, deliberately naive
-      # walk (reference_where_holds?) — never Runtime::ReferenceHop's
-      # partition/fold/in-clause. Sharing that algorithm would have made
-      # this oracle blind to exactly the code the hop feature adds: every
-      # phase of a shared fold would still get diffed against the native
-      # adapters, but the fold itself — the empty candidate set, a
-      # duplicate id, a dangling reference, a chain's inside-out
-      # resolution order — would only ever be compared against itself.
+      # Hop clauses use a deliberately naive walk (reference_where_holds?), not
+      # ReferenceHop's fold; sharing that would blind the oracle to it.
       #
-      # @param domain [String, Symbol] the domain `aggregate` belongs to
-      # @param aggregate [Bluebook::Aggregate] the aggregate the query is declared on
-      # @param query_name [String] the query's declared name, or an entity query's
-      #   dotted `"Entity.Query"` name
-      # @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
+      # @return [Array<Hash>] one Hash per matching record, `:id` merged in last
       # @raise [Runtime::UnknownVerb] if `query_name` names no declared query
-      # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its
-      #   declared type
-      # @raise [Runtime::WiringError] if the aggregate's repository cannot be resolved
+      # @raise [Runtime::TypeMismatch] if an argument cannot be coerced to its type
       def reference_call(domain, aggregate, query_name, args)
         return entity_rows(domain, aggregate, query_name, args) if query_name.include?(".")
 
@@ -130,25 +82,15 @@ module Hecks
       def interpret(records, declared, args, domain: nil)
         matched = records.select { |r| declared.wheres.all? { |w| where_holds?(w, r, args, domain: domain) } }
         ordered = ordered(matched, declared.order_by, declared.null_semantics)
-        # **Offset first, then limit** — the order SQL means by `LIMIT n
-        # OFFSET m`, and the order Ports::Query::InMemory#execute already
-        # applies (see that file's own comment). Without reading
-        # `declared.offset`, offset would silently vanish for any query
-        # answered here, not just come out reversed.
+        # Offset before limit, as SQL's `LIMIT n OFFSET m` and Ports::Query::InMemory do.
         skipped = declared.offset ? ordered.drop(resolve_query_value(declared.offset.value, args).to_i) : ordered
         capped  = declared.limit ? skipped.first(resolve_query_value(declared.limit.value, args).to_i) : skipped
 
-        # id last — see the native-path comment above; same clobbering
-        # risk for the in-memory reference interpreter's own rows.
         capped.map { |r| r.state.merge(id: r.id) }
       end
 
-      # `interpret`'s own twin, for reference_call alone — same
-      # select/order/limit shape, but a clause that hops through a
-      # reference is answered by reference_where_holds? instead of the
-      # plain FieldPath.dig(record, field) `where_holds?` uses (which
-      # has no concept of a reference at all — it would just read the
-      # raw id straight off the record and compare that).
+      # Twin of `interpret` for reference_call: hop clauses go through
+      # reference_where_holds?, which `where_holds?` cannot follow.
       def reference_interpret(records, declared, args, domain:, shape:)
         matched = records.select do |r|
           declared.wheres.all? do |w|
@@ -156,24 +98,14 @@ module Hecks
           end
         end
         ordered = ordered(matched, declared.order_by, declared.null_semantics)
-        # **Offset first, then limit** — same fix, same reasoning, as
-        # #interpret's own rows above.
         skipped = declared.offset ? ordered.drop(resolve_query_value(declared.offset.value, args).to_i) : ordered
         capped  = declared.limit ? skipped.first(resolve_query_value(declared.limit.value, args).to_i) : skipped
 
-        # id last — same reasoning, same fix, as interpret's own rows.
         capped.map { |r| r.state.merge(id: r.id) }
       end
 
-      # **The naive reading of a hop**: not a fold, not an id set — for
-      # each candidate row, walk the reference by hand and dig the
-      # field out of whatever it actually points at. A nil reference,
-      # or one that resolves to nothing (a dangling id), makes the
-      # whole clause false outright, whatever the comparator — "points
-      # at a client that is not active" is false for a proposal with no
-      # client at all, the same way it is false for one whose client
-      # really is active; falling through to holds?(clause, nil, args)
-      # instead would answer `ne` wrong (nil != "active" is true).
+      # Walks each reference by hand. A nil or dangling reference makes the whole clause
+      # false whatever the comparator; comparing nil directly would answer `ne` true.
       def reference_where_holds?(clause, record, args, domain:, shape:)
         step = QuerySpecification::HopPath.next_hop(clause.field, shape.attributes)
         return where_holds?(clause, record, args) unless step
@@ -205,21 +137,13 @@ module Hecks
 
         ordered = ordered_elements(rows, declared.order_by, declared.null_semantics,
                                    parent_key, entity.identity_heads)
-        # **Offset first, then limit** — same fix, same reasoning, as
-        # #interpret's own rows above. `entity_rows` is the only engine
-        # for entity/sub-list queries, so a declared offset here silently
-        # vanished for every entity query, not merely one path among
-        # several.
+        # Entity queries have no native path, so offset must be applied here.
         skipped = declared.offset ? ordered.drop(resolve_query_value(declared.offset.value, args).to_i) : ordered
         declared.limit ? skipped.first(resolve_query_value(declared.limit.value, args).to_i) : skipped
       end
 
-      # The three declarations `entity_rows` needs before it can read a
-      # single record — the entity itself, its declared query, and the
-      # list attribute that holds it on the aggregate. Extracted from
-      # `entity_rows` (pure extraction, same lookups, same order, same
-      # UnknownVerb refusals) purely to separate "which declarations does
-      # this dotted name resolve to" from the row-computation that follows.
+      # Resolves a dotted name to the entity, its declared query and the list attribute
+      # holding it, refusing with UnknownVerb when any is missing.
       def resolve_entity_query(aggregate, entity_name, query_name)
         entity = aggregate.entities.find { |piece| piece.hecks_name == entity_name } ||
                  raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_unknown",
@@ -233,35 +157,19 @@ module Hecks
         [entity, declared, list_attr]
       end
 
-      # FieldPath.dig, not a raw `element[clause.field.to_sym]` — a dotted
-      # `where` (`where "price.cents" < 100`) needs the same segment-by-
-      # segment walk every other query path already gets. Reading the whole
-      # dotted string as one key always missed — `element[:"price.cents"]`
-      # is never a real key — so a dotted where on an entity query
-      # silently matched nothing, on the only engine entity queries have.
+      # FieldPath.dig, not `element[clause.field.to_sym]`: a dotted field such as
+      # "price.cents" is never a single key.
       def element_where_holds?(clause, element, args)
         holds?(clause, QuerySpecification::FieldPath.dig(element, clause.field), args)
       end
 
-      # A row's own key. A sub-list row is a hydrated entity element (symbol-keyed
-      # since every adapter decodes through `Ports::Persistence::StateCodec` and
-      # `EntityListCoercion#hydrate_entity_list` symbolizes each element — PR A4
-      # removed the string-spelling fallback that coped with the old per-adapter
-      # shapes). It rides `comparable` for the same reason a where-clause does : an
-      # identity is a value object, and `to_s` on one is an object address — a sort key
-      # that differs run to run, which is worse than the store order it replaced.
+      # Sub-list rows are symbol-keyed because every adapter decodes through
+      # `Ports::Persistence::StateCodec`.
       def cell(row, key) = row[key.to_sym]
 
-      # A sub-list row is identified by its parent and then its own key : two
-      # entities under different parents can share a sequence, so the parent has
-      # to lead or the tie is not broken at all.
-      #
-      # Every key the piece is known by, in declaration order, for the same
-      # reason the parent leads: a part that ties is a part that breaks no tie.
-      # This took `identified_by`, which is the single head and is nil the
-      # moment an identity has two parts — and `cell(row, nil)` calls
-      # `nil.to_sym`, so a query against a composite piece did not sort wrongly,
-      # it raised. A piece known by one key sorts exactly as it did.
+      # Orders by parent first, then every key of the piece in declaration order: two
+      # entities under different parents can share a sequence, and a composite identity
+      # has no single head (`cell(row, nil)` would raise).
       def ordered_elements(rows, order_by, null_semantics, parent_key, entity_keys)
         field = order_by&.field
         Ports::Query::Ordering.apply(
@@ -276,13 +184,8 @@ module Hecks
         holds?(clause, QuerySpecification::FieldPath.dig(record, clause.field), args, record: record, domain: domain)
       end
 
-      # The comparator table itself lives in
-      # QuerySpecification::Common::Comparison, shared with
-      # Ports::Query::InMemory#holds? rather than each carrying its own
-      # copy — two copies once drifted: `none_in_state` reached only one
-      # of them, and `comparable` disagreed about value objects with two
-      # numeric members. What stays here is how a value is reached for
-      # this path: the registry is instance state rather than an argument.
+      # The comparator table is shared with Ports::Query::InMemory#holds? through
+      # QuerySpecification::Common::Comparison so the two cannot drift.
       def holds?(clause, held, args, record: nil, domain: nil)
         QuerySpecification::Common::Comparison.holds?(
           clause.op, comparable(held), comparable(resolve_query_value(clause.value, args)), registry: @registry
@@ -293,49 +196,14 @@ module Hecks
         value.is_a?(Symbol) ? args[value] : value
       end
 
-      # `boundary: false` always (C3.8 — a query's declared argument types
-      # name the argument for callers and generators, never a runtime
-      # shape checked here). A null required value-object-typed query
-      # argument, though, is not a runtime-shape question at all: C3.7
-      # says a named query's declared value-object arguments are checked
-      # the same way a command argument's own is, so a `nil` offered for
-      # a non-optional value-object-typed query attribute
-      # (Governance::RoleAssignment.AssignmentsForActor's `actor_id`, say)
-      # has to refuse — passing it through unchecked would let it through
-      # as a silent, unfiltered query instead, a real
-      # Ruby/Rust divergence the fuzzer caught (QualityControl BUG#2).
-      #
-      # `checked_vo?` true is handled by `null_vo_argument!` directly,
-      # never by routing through `Value.for_attribute(argument: true)`
-      # into the shared `Value::Coercion#nil_argument` the command door
-      # (`Interpreting#coerce_declared_arguments`) still uses — that
-      # method builds a null value object from zero fields, which
-      # succeeds (silently absorbing the null via the type's own field
-      # defaults) whenever every field happens to have one
-      # (`Lease.Expired`'s `now`, a `LeaseInstant` with a `default: 0`
-      # field; `Account.Overdrawn`/`HighBalance`/`StrictlyAbove`/
-      # `AtMost`'s `floor`/`cap`, a two-defaulted-field `Money`) and only
-      # refuses when a field has none (`Order.CostingLessThan`'s
-      # `ceiling`, a defaultless `Price`) — a real query-side divergence
-      # from Rust, which always refuses `TypeMismatch` on an explicit
-      # null argument regardless of any default (QualityControl BUG#36).
-      # `null_vo_argument!` instead treats an explicit null exactly the
-      # way `Value.fields_for` already treats any other wrong-shaped
-      # (non-Hash, non-Value) value offered for that same attribute — a
-      # single-field value object auto-wraps into `{field: nil}` (whose
-      # own `nil` is a present key, so `Value.build`'s `apply_defaults`
-      # never fills it, and `check_required_fields` refuses it exactly
-      # as any other missing required field would); a multi-field value
-      # object refuses immediately with the same `value_object_shape`
-      # wording an ordinary wrong-shaped scalar already gets. Command
-      # arguments are deliberately untouched — this is a query-only
-      # door; `nil_argument`'s own default-absorbing fallback still
-      # governs a null command argument exactly as it always has.
+      # Coerces with `boundary: false`: a query's declared argument types are not a
+      # runtime shape check. The exception is a nil for a required value-object-typed
+      # argument, which must refuse as a command argument does; passing it through
+      # would run an unfiltered query (a Ruby/Rust divergence).
       #
-      # C3.8's own bare-scalar carve-out stays intact: `checked_vo?` is
-      # only true for a value-object-typed attribute, so a bare
-      # `String`/`Integer` query argument offered nil still passes
-      # through exactly as it always did.
+      # It does not use `Value::Coercion#nil_argument`, which builds a null value object
+      # from field defaults and only refuses when a field has none. `null_vo_argument!`
+      # refuses like any other wrong-shaped value. Command arguments are untouched.
       def normalize_args(aggregate, declared, args)
         declared.attributes.each_with_object(args.dup) do |attribute, normalized|
           next unless normalized.key?(attribute.name)
@@ -357,10 +225,7 @@ module Hecks
         !Value.value_object_for(aggregate, attribute.type).nil?
       end
 
-      # Only ever reached when `checked_vo?` has already confirmed the
-      # attribute's type resolves to a real value object — see its own
-      # comment above for why this refuses unconditionally, never
-      # absorbing the null via the type's own field defaults.
+      # Refuses a nil for a value-object argument; never absorbs it via field defaults.
       def null_vo_argument!(aggregate, attribute)
         value_object = Value.value_object_for(aggregate, attribute.type)
         Value.build(value_object, Value.fields_for(value_object, attribute.name, nil), aggregate)
@@ -368,15 +233,8 @@ module Hecks
 
       def comparable(value) = QuerySpecification::Common::Comparison.comparable(value)
 
-      # FieldPath.dig, not a raw `record[field]` — `record` is an Instance
-      # here, and a dotted order_by (`order_by "price.cents"`) is a
-      # single symbol key (`:"price.cents"`) that never matches anything
-      # `Instance#[]` actually holds, so a dotted order_by silently sorted
-      # by all-nil (the identity tier alone deciding every tie) on this,
-      # the reference/no-native-hook engine — the same bug already fixed
-      # for `where` (see `where_holds?` above) and for entity rows (see
-      # `ordered_elements` below), just not yet for this, the aggregate-
-      # level order_by.
+      # FieldPath.dig, not `record[field]`: a dotted order_by is one symbol key that
+      # `Instance#[]` never holds, so it would sort by all-nil.
       def ordered(records, order_by, null_semantics = nil)
         field = order_by&.field
         Ports::Query::Ordering.apply(records, order_by, null_semantics,

data/lib/hecks/runtime/reaction_invocation.rb

@@ -5,27 +5,19 @@ require_relative "value"
 
 module Hecks
   module Runtime
-    # Turns facts selected by a policy or process manager into the same
-    # receiver/payload envelope an outside caller uses. A reaction declares
-    # both receiver identities and facts through one `with:` map, so this is
-    # the one compatibility seam that separates them after resolving the
-    # declaration and before re-entering the dispatcher.
+    # Turns facts a policy or process manager selected into the receiver/payload
+    # envelope an outside caller uses.
     module ReactionInvocation
       Target = Struct.new(:aggregate, :entities, :command, keyword_init: true)
       # :facts, not :values — Struct.new already defines #values (every
-      # member's own value, in order); naming this field :values silently
-      # shadowed that with the single Hash it actually holds.
+      # member's own value, in order); naming this field :values would
+      # silently shadow that with the single Hash it actually holds.
       Scope = Struct.new(:name, :facts, keyword_init: true)
 
       module_function
 
-      # Reports whether a reaction declared an explicit `with:` projection.
-      #
-      # An omitted projection and an explicitly empty `with: {}` both hold
-      # as the same empty array on the holding IR. Builders preserve
-      # declaration presence off-wire, in `@projection_declared`;
-      # reconstructed/legacy IR without that ivar falls back to reading
-      # presence off whether `with_spec` is non-empty.
+      # Reports whether a reaction declared an explicit `with:` projection;
+      # an omitted projection and an explicit `with: {}` both count as none.
       #
       # @param declaration [Bluebook::Policy, Bluebook::DispatchSpec] the reacting
       #   declaration to check
@@ -38,27 +30,16 @@ module Hecks
         end
       end
 
-      # Resolves a declared `with:` projection against the scopes and bindings visible to it.
-      #
-      # A reaction's source names resolve lexically, not globally. Policies
-      # supply one event/row scope. Process managers supply current event then
-      # opening-event memory, while correlation is an explicit binding ahead
-      # of both. Missing names are refused here rather than materialized as nil
-      # and accidentally presented as target command facts.
+      # Resolves a declared `with:` projection against the scopes and bindings visible
+      # to it, refusing a name resolved in neither rather than passing it as nil.
       #
-      # @param with_spec [Hash{Symbol => Object}] each target fact name mapped to its source:
-      #   a Symbol naming a fact visible in `bindings` or `scopes`, or any other value taken
-      #   as a literal
-      # @param scopes [Array<Hecks::Runtime::ReactionInvocation::Scope, Array(String,
-      #   Hash)>] the named fact scopes to resolve a Symbol source against, checked in order;
-      #   a bare `[name, facts]` pair is wrapped into a `Scope`
-      # @param bindings [Hash] explicit bindings (such as a saga's correlation key), checked
-      #   before any scope
+      # @param with_spec [Hash] fact name => source: a Symbol looked up in `bindings`/`scopes`,
+      #   or any other value taken as a literal
+      # @param scopes [Array<Scope, Array(String, Hash)>] named fact scopes, checked in order
+      # @param bindings [Hash] explicit bindings (e.g. a saga's correlation key), checked first
       # @param label [String] names this resolution in an `UnknownArgument` refusal
-      # @return [Hash{Symbol => Object}] `with_spec`'s keys mapped to their resolved,
-      #   materialized values
-      # @raise [Runtime::UnknownArgument] if a Symbol source names a fact visible in no
-      #   binding and no scope
+      # @return [Hash] `with_spec`'s keys mapped to their resolved, materialized values
+      # @raise [Runtime::UnknownArgument] if a Symbol source is visible in no binding or scope
       def resolve_mapping(with_spec:, scopes:, bindings: {}, label: "reaction")
         normalized_bindings = bindings.transform_keys(&:to_sym)
         normalized_scopes = scopes.map do |scope|
@@ -72,10 +53,6 @@ module Hecks
         end
       end
 
-      # One `with:` source, resolved — pulled out of resolve_mapping
-      # because it is a pure function of its own arguments (a literal, a
-      # binding, or a name visible in some scope), with no dependency on
-      # anything else resolve_mapping's own to_h block is doing.
       def resolved_mapping_value(source, bindings, scopes, label)
         return source unless source.is_a?(Symbol)
         return bindings.fetch(source) if bindings.key?(source)
@@ -83,13 +60,7 @@ module Hecks
         visible = scopes.find { |scope| scope.facts.key?(source) }
         unless visible
           names = scopes.map(&:name).join(" then ")
-          # **What is visible, named**. A refusal that only says which name is
-          # missing sent a modeler guessing field after field
-          # (`number`, `reference`…) at a fan-out row that is addressed
-          # by one key — `account`, the lowercase aggregate — which
-          # nothing else in the domain spells out. The names each scope
-          # actually offers are the whole diagnosis; the refusal now
-          # lists them, scope by scope.
+          # Names every visible option so a caller isn't left guessing at fields.
           offered = scopes.map { |scope| "#{scope.name}: #{scope.facts.keys.sort.join(', ')}" }.join("; ")
           raise UnknownArgument,
                 "#{label}'s with: reads :#{source}, which is not visible in #{names} (visible — #{offered})"
@@ -98,39 +69,18 @@ module Hecks
       end
       private_class_method :resolved_mapping_value
 
-      # A reaction without an explicit projection retains wholesale legacy
-      # forwarding. Choosing `with:` opts into the strict envelope: only target
-      # command attributes enter `with:`, while identities become `to:`.
-      # `consumed` accumulates across the aggregate-identity and entity-
-      # identity steps below, and refuse_unconsumed! at the end reads the
-      # final list — an ordering dependency threaded through one shared
-      # local. Already leans on private helpers (identity_for,
-      # source_receiver_for, command_facts, refuse_unconsumed!) for every
-      # piece that is self-contained; what remains is the sequencing
-      # itself, which further splitting would only relocate, not remove.
+      # A reaction without an explicit `with:` projection forwards its payload
+      # wholesale; an explicit one builds a strict `{to:, with:}` envelope instead.
       # rubocop:disable-next Metrics/MethodLength, Metrics/PerceivedComplexity
-      #
-      # @param registry [Runtime::Registry] the booted registry to resolve `verb` against
       # @param verb [String] the fully qualified target command verb
-      # @param projected [Hash] the facts to send, already resolved (e.g. by
-      #   `resolve_mapping`) or, for a legacy reaction, the raw event/row payload
-      # @param explicit [Boolean] true when the reaction declared its own `with:` projection
-      #   (`projection_declared?`); false forwards `projected` wholesale as legacy args
-      # @param passthrough [Array<String, Symbol>] extra fact names allowed to ride along
-      #   unconsumed, beyond the receiver identity and declared command facts
-      # @param source_receiver [Hash{Symbol => Object}, nil] the triggering event's own
-      #   `{aggregate:, identity:}`, offered as a same-aggregate receiver when nothing else
-      #   supplies one; nil when there is no such event to inherit from
-      # @return [Hash{Symbol => Object}] `{to:, with:}` for an explicit projection targeting
-      #   a non-creating command (`with:` only for a creating command); otherwise `projected`
-      #   (with `to:` merged in when a receiver could be inherited)
-      # @raise [Runtime::UnknownVerb] if `verb` does not resolve to a declared command,
-      #   entity command, or port operation (only when `explicit` is true; a legacy call
-      #   resolving `verb` only to check inheritance swallows this and forwards unchanged)
-      # @raise [Runtime::TypeMismatch] if an explicit projection resolves no receiver
-      #   identity for the target aggregate or one of its entities
-      # @raise [Runtime::UnknownArgument] if an explicit projection's facts include a name
-      #   that is neither a consumed receiver identity nor a declared command fact
+      # @param projected [Hash] resolved facts, or the raw payload when not `explicit`
+      # @param explicit [Boolean] whether the reaction declared its own `with:` projection
+      # @param passthrough [Array<String, Symbol>] extra fact names allowed unconsumed
+      # @param source_receiver [Hash, nil] an inheritable receiver from the triggering event
+      # @return [Hash] `{to:, with:}` when explicit, else `projected` merged with `to:`
+      # @raise [Runtime::UnknownVerb] if `verb` does not resolve (only when `explicit`)
+      # @raise [Runtime::TypeMismatch] if no receiver identity resolves for an explicit target
+      # @raise [Runtime::UnknownArgument] if an explicit projection has an undeclared fact
       def build(registry:, verb:, projected:, explicit:, passthrough: [], source_receiver: nil)
         args = projected.transform_keys(&:to_sym)
         unless explicit
@@ -144,16 +94,9 @@ module Hecks
           rescue UnknownVerb
             return args
           end
-          # An entity target has no shape this branch can build — an
-          # implicit (unprojected) `to:` is always a bare scalar, the
-          # aggregate's own identity alone; an entity command's receiver is
-          # `{aggregate:, entities:}`, which needs the entity's own
-          # identity too, and nothing here resolves one (the same "cannot
-          # invent an entity identity" limit `source_receiver_for`'s own
-          # comment already states). So this stays exactly the pre-BUG#6
-          # behavior for an entity target: no receiver is lifted, and the
-          # payload forwards wholesale, unchanged, same as when there is
-          # no `source_receiver` at all.
+          # An entity target's receiver needs `{aggregate:, entities:}`, but nothing
+          # here can invent the entity's own identity — so no receiver is lifted here;
+          # the payload forwards wholesale, same as with no `source_receiver` at all.
           return args unless target.entities.empty?
 
           inherited_receiver = source_receiver_for(target, source_receiver)
@@ -212,18 +155,9 @@ module Hecks
 
         *entity_names, command_name = command_path.split(".")
 
-        # A port operation, reached by the same two-segment tail shape an
-        # entity command uses ("Head.Rest") — checked first, same order
-        # `Dispatcher#dispatch` already resolves a live verb in (an
-        # aggregate that declared both a port and an entity of the same
-        # name would resolve to the port there too; no domain in this
-        # corpus does). A port has no `entities` of its own — the
-        # receiver is always the aggregate itself — so `Target#entities`
-        # stays empty and `#command` holds the `PortOperation`, which
-        # answers `#creates?` (always false) the same way an ordinary
-        # `Command` does, letting `source_receiver_for` lift a same-
-        # aggregate policy's own Event.id as the operation's receiver
-        # exactly as it already does for a plain command.
+        # A port operation shares the two-segment tail shape an entity command
+        # uses ("Head.Rest"); checked first, matching the order
+        # `Dispatcher#dispatch` already resolves a live verb in.
         if entity_names.one? && (port = aggregate.port(entity_names.first))
           operation = port.operation(command_name)
           raise UnknownVerb, "reaction target #{verb.inspect} does not resolve to a declared port operation" unless operation
@@ -259,49 +193,13 @@ module Hecks
       end
       private_class_method :aggregate_aliases
 
-      # Event.id names the aggregate that emitted the event. It can therefore
-      # supply only the receiver of a non-creating command on that same root;
-      # it cannot address another aggregate, invent an entity identity, or turn
-      # a creation into a mutation. An explicit projected receiver is resolved
-      # first and remains authoritative.
-      #
-      # Answers regardless of `target.entities` — the value this method hands
-      # back is only ever the root aggregate's own identity (`source_receiver`
-      # carries nothing else: `event.aggregate`/`event.id` name the emitting
-      # aggregate, never one of its entities). An entity target's own identity
-      # is resolved entirely separately, from `args` (`build`'s own `entity_
-      # identities` loop) — this method is never consulted for it, so
-      # answering for an entity target does not "invent an entity identity"
-      # any more than answering for a plain one invents that identity; it was
-      # already the one thing this method has ever supplied. `build`'s own
-      # explicit branch (below) already applies this correctly either way
-      # (`aggregate_identity ||= inherited_receiver`, entity identities read
-      # from `args` regardless) — the caller that actually needed a guard
-      # here is the implicit one, above, which has no shape to build a
-      # `{aggregate:, entities:}` receiver from an inherited scalar alone,
-      # and now guards itself for exactly that reason instead of this method
-      # doing it on that caller's behalf and, as a side effect, also refusing
-      # the explicit caller's own legitimate case — confirmed missing until
-      # `qa/stress_domains/waybill` (BUG#6) exercised it for the first time
-      # anywhere in the corpus: a saga dispatching into a nested entity's own
-      # command, inheriting its aggregate receiver from the event that
-      # triggered it.
+      # An event's own identity can supply the receiver of a non-creating command on
+      # the same aggregate root; it never addresses another aggregate or an entity.
       def source_receiver_for(target, source_receiver)
         return nil unless source_receiver
-        # `target.command.creates?` alone misreads every entity command —
-        # `Behaviour::Command#creates?`'s own comment: "a verb declared on
-        # an entity always acts on that piece... which means `creates?`
-        # answers true for every one of them" (it never sets `@references`
-        # the way an aggregate-level command's own `reference_to` does,
-        # not because it brings anything new into being). `build`'s own
-        # `if target.entities.empty? && target.command.creates?` guard,
-        # 20-odd lines below, already reads `creates?` correctly for
-        # exactly this reason — an entity command is never a genuine
-        # creation, whatever `creates?` alone answers — so this checks the
-        # same compound condition instead of the bare, misleading half of
-        # it. Left unfixed, an entity target's own receiver was refused
-        # here even after this method stopped refusing on `target.entities`
-        # alone — the second half of BUG#6's own fix.
+        # `target.command.creates?` alone misreads every entity command, which always
+        # answers true for `creates?` though it never creates anything (Behaviour::
+        # Command#creates?) — checked as the same compound condition `build` uses below.
         return nil if target.entities.empty? && target.command.creates?
 
         source = source_receiver.transform_keys(&:to_sym)