hecks 1.2.0 → 1.4.0

data/lib/hecks/runtime/port_operation_interpreter.rb

@@ -19,7 +19,7 @@ module Hecks
       include Interpreting
       include CommandInterpreter::ArgumentGate
 
-      Context = Struct.new(:domain, :aggregate, :operation, :args, :route, :instance, :result)
+      Context = Struct.new(:domain, :aggregate, :operation, :args, :route, :instance, :result, :invocation)
 
       DISPATCH_ORDER = %i[
         refuse_unknown_arguments refuse_absent_arguments normalize_args resolve_references resolve_route emit
@@ -30,9 +30,12 @@ module Hecks
         @rules    = rules
       end
 
-      def call(domain, aggregate, operation, args, route:)
-        ctx = Context.new(domain, aggregate, operation, args)
-        ctx.route = route
+      # `invocation` — the `Runtime::Invocation` `Dispatcher` built;
+      # `ctx.args` is its `to_args`, `ctx.route` its `target`.
+      def call(domain, aggregate, operation, invocation)
+        ctx = Context.new(domain, aggregate, operation, invocation.to_args)
+        ctx.invocation = invocation
+        ctx.route = invocation.target
         run_dispatch_order(DISPATCH_ORDER, ctx)
         ctx.result
       end
@@ -66,13 +69,13 @@ module Hecks
         ctx.result = step(:emit) { ctx.operation.outbound? ? ask(ctx) : emit(ctx) }
       end
 
-      # THE DOMAIN CALLING OUT, AND BOTH ENDINGS RECORDED.
+      # The domain calling out, and both endings recorded.
       #
       # The adapter is found the same way every other port's is — by name,
       # across whatever adapters this boot loaded — so an `asks` is bound by
       # an adapter declaring `port "IssueTracker"` and nothing new to learn.
       #
-      # EVERY FAILURE IS AN ANSWER. A raise from the far side of a boundary is
+      # Every failure is an answer. A raise from the far side of a boundary is
       # not an exception in this domain's terms, it is the outside saying no,
       # and the chapter already named the word for that. So the rescue is
       # deliberately wide: a timeout, a bad credential, an adapter that does
@@ -80,22 +83,22 @@ module Hecks
       # `refuses` event, carrying what was said. A policy reacts to it, a
       # retry counter reads it, and nothing has to catch anything.
       #
-      # AN ASK IS HANDED THE RECORD IT IS ABOUT.
+      # An ask is handed the record it is about.
       #
-      # An INBOUND operation deliberately cannot read state — it is the
+      # An inbound operation deliberately cannot read state — it is the
       # anti-corruption boundary, translating a fact from outside, and letting
       # it read the aggregate would make it a second place rules live. That
       # rule was written for that direction and does not survive the crossing.
       #
       # An outbound one almost always needs the record. `asks "File"` names
       # `reference_to Ticket` and the adapter needs the ticket's repository,
-      # title and body — which are ON the ticket, and which the policy that
+      # title and body — which are on the ticket, and which the policy that
       # triggered this cannot supply because a command's event payload is its
-      # ARGUMENTS, not its state. Without this, every ask would have to have
+      # arguments, not its state. Without this, every ask would have to have
       # its data re-passed through the command that fired it, so the same text
       # would live in two places and could differ.
       #
-      # ARGUMENTS WIN over state, because an argument is what THIS call said
+      # Arguments win over state, because an argument is what this call said
       # and state is what the record happens to hold.
       def ask(ctx)
         payload = held_state(ctx).merge(materialise(ctx.args))
@@ -105,13 +108,13 @@ module Hecks
         announce(ctx, ctx.operation.refuses, ctx.args.merge(refusal: { value: "#{e.class}: #{e.message}" }))
       end
 
-      # THE ANSWER IS SPREAD, NOT NESTED — and that is what makes the loop
-      # close. A policy re-enters its target with the event payload VERBATIM;
+      # The answer is spread, not nested — and that is what makes the loop
+      # close. A policy re-enters its target with the event payload verbatim;
       # it cannot reach inside a key. So an answer tucked under `answered:`
       # can be read by a human and by nothing else, and the command that
       # should record the issue number never gets one.
       #
-      # Spread, the adapter's own keys ARE the arguments of whatever command
+      # Spread, the adapter's own keys are the arguments of whatever command
       # reacts to the answering event. Which is a real contract on the adapter
       # — it must return what that command takes, in the shape the runtime
       # coerces (`{ number: { value: 43 } }`, not `43`) — and naming it here
@@ -134,7 +137,7 @@ module Hecks
         end
       end
 
-      # THE RECORD, IF THERE IS ONE. A record that does not exist yet is not
+      # The record, if there is one. A record that does not exist yet is not
       # an error here — the ask still goes, carrying only its arguments, and
       # whatever the adapter makes of that is its own business. Refusing
       # would put a second existence check behind the one `resolve_references`
@@ -145,10 +148,10 @@ module Hecks
         {}
       end
 
-      # THE PORT THIS OPERATION BELONGS TO, found by asking the aggregate
+      # The port this operation belongs to, found by asking the aggregate
       # rather than threading it through the call — the dispatcher already
       # resolved it once to get here, and a second parameter carried purely so
-      # this method can read it would be a parameter every OTHER step ignores.
+      # this method can read it would be a parameter every other step ignores.
       def port_name_for(ctx)
         owning = ctx.aggregate.ports.find { |port| port.operations.any? { |op| op.equal?(ctx.operation) } }
         owning&.name or raise WiringError,
@@ -185,9 +188,9 @@ module Hecks
         [event]
       end
 
-      # THE ONE PLACE THIS DIFFERS FROM CommandRules::Emission — there is no
+      # The one place this differs from CommandRules::Emission — there is no
       # mutated instance to read an id off, because nothing was hydrated or
-      # saved. The record this event is ABOUT is named by whichever attribute
+      # saved. The record this event is about is named by whichever attribute
       # is a reference to the owning aggregate (PortOperationBuilder#build
       # already refused to build an operation with none), so its coerced
       # value — already a plain id, never an object, per

data/lib/hecks/runtime/query_interpreter.rb

@@ -15,7 +15,7 @@ module Hecks
     # 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
+    # #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.
@@ -32,10 +32,10 @@ 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
+        # 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.
@@ -51,14 +51,14 @@ module Hecks
         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
+          # `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)` used to let it silently
+          # it over a `{id:}.merge(state)` used to 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
+          # A query row is an answer, not a handle. Mutating one edits
           # nobody's state and silently disagrees with the store.
           return Freezer.deep(records.map { |record| record.state.merge(id: record.id) })
         end
@@ -66,18 +66,18 @@ module Hecks
         Freezer.deep(interpret(repository.all, declared, args, domain: domain))
       end
 
-      # The REFERENCE answer — this interpreter's own evaluation, never an
+      # 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.
       #
-      # A hop clause is answered here by its OWN, deliberately naive
+      # 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
+      # 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
+      # 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.
@@ -95,14 +95,14 @@ module Hecks
 
       def declared_query(aggregate, query_name)
         aggregate.query(query_name) ||
-          raise(UnknownVerb, RefusalWording.render("UnknownVerb", "no_query",
-                                                   aggregate: aggregate.hecks_name, query: query_name.inspect))
+          raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "no_query",
+                                                        aggregate: aggregate.hecks_name, query: query_name))
       end
 
       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 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). This interpreter used to
         # never read declared.offset at all — offset silently vanished for
@@ -110,7 +110,7 @@ module Hecks
         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
+        # 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
@@ -120,7 +120,7 @@ module Hecks
       # 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).
+      # raw id straight off the record and compare that).
       def reference_interpret(records, declared, args, domain:, shape:)
         matched = records.select do |r|
           declared.wheres.all? do |w|
@@ -128,20 +128,20 @@ module Hecks
           end
         end
         ordered = ordered(matched, declared.order_by, declared.null_semantics)
-        # OFFSET FIRST, THEN LIMIT — same fix, same reasoning, as
+        # **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.
+        # 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
+      # **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
+      # 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)
@@ -177,8 +177,8 @@ 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
+        # **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.
@@ -186,31 +186,28 @@ module Hecks
         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
+      # 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.
       def resolve_entity_query(aggregate, entity_name, query_name)
         entity = aggregate.entities.find { |piece| piece.hecks_name == entity_name } ||
-                 raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_unknown",
-                                                          aggregate: aggregate.hecks_name, entity: entity_name.inspect))
+                 raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_unknown",
+                                                               aggregate: aggregate.hecks_name, entity: entity_name))
         declared = entity.query(query_name) ||
-                   raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_query_missing",
-                                                            entity: entity_name, query: query_name.inspect))
+                   raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_query_missing",
+                                                                 entity: entity_name, query: query_name))
         list_attr = aggregate.attributes.find { |a| a.list? && a.type.to_s == entity_name } ||
-                    raise(UnknownVerb, RefusalWording.render("UnknownVerb", "entity_holds_no_list",
-                                                             aggregate: aggregate.hecks_name, entity: entity_name))
+                    raise(UnknownVerb, RefusalWording.render_site("UnknownVerb", "entity_holds_no_list",
+                                                                  aggregate: aggregate.hecks_name, entity: entity_name))
         [entity, declared, list_attr]
       end
 
-      # FieldPath.dig, not a raw `element[clause.field.to_sym]` — an
-      # entity sub-list row is a plain hash merged from stored state
-      # (mixed string/symbol keys depending on adapter, per `#cell`'s own
-      # comment below), and a dotted `where` (`where "price.cents" < 100`)
-      # needs the same segment-by-segment walk every other query path
-      # already gets. Reading only the symbol spelling of the WHOLE
+      # 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.
@@ -218,28 +215,22 @@ module Hecks
         holds?(clause, QuerySpecification::FieldPath.dig(element, clause.field), args)
       end
 
-      # A row's own key, however the store spells it. A sub-list row is a plain hash
-      # merged from stored state, so its keys arrive as strings from one adapter and
-      # symbols from another — and reading only one spelling gave every row the SAME
-      # identity, which is a tie, which is the exact nondeterminism this tier exists
-      # to remove. 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
+      # 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.
-      # `key?` decides which spelling answers, never `||` — a row whose
-      # value is a genuinely-held `false` must not fall through to the
-      # other spelling (usually absent) and land on `nil`.
-      def cell(row, key)
-        sym = key.to_sym
-        row.key?(sym) ? row[sym] : row[key.to_s]
-      end
+      def cell(row, key) = row[key.to_sym]
 
-      # A sub-list row is identified by its PARENT and then its own key : two
+      # 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
+      # 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
+      # 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.
@@ -262,7 +253,7 @@ module Hecks
       # Ports::Query::InMemory#holds? used to carry a copy each and the
       # two 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
+      # members. What stays here is how a value is reached for this
       # path: the registry is instance state rather than an argument.
       def holds?(clause, held, args, record: nil, domain: nil)
         QuerySpecification::Common::Comparison.holds?(
@@ -274,15 +265,79 @@ 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 (as this used to)
+      # 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.
+      #
+      # 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.
       def normalize_args(aggregate, declared, args)
         declared.attributes.each_with_object(args.dup) do |attribute, normalized|
           next unless normalized.key?(attribute.name)
 
-          normalized[attribute.name] = Value.for_attribute(aggregate, attribute, normalized[attribute.name],
-                                                           boundary: false)
+          value = normalized[attribute.name]
+          normalized[attribute.name] = if checked_vo?(aggregate, attribute, value)
+                                         null_vo_argument!(aggregate, attribute)
+                                       else
+                                         Value.for_attribute(aggregate, attribute, value, boundary: false)
+                                       end
         end
       end
 
+      def checked_vo?(aggregate, attribute, value)
+        return false unless value.nil?
+        return false if attribute.optional? || attribute.list? || attribute.reference?
+        return false unless aggregate.respond_to?(:value_object)
+
+        !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.
+      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)
+      end
+
       def comparable(value) = QuerySpecification::Common::Comparison.comparable(value)
 
       # FieldPath.dig, not a raw `record[field]` — `record` is an Instance

data/lib/hecks/runtime/reaction_invocation.rb

@@ -49,7 +49,7 @@ module Hecks
         end
       end
 
-      # ONE `with:` SOURCE, RESOLVED — pulled out of resolve_mapping
+      # 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.
@@ -60,10 +60,10 @@ 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
+          # **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
+          # 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.
@@ -80,12 +80,12 @@ module Hecks
       # 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
+      # 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
+      # piece that is self-contained; what remains is the sequencing
       # itself, which further splitting would only relocate, not remove.
-      # rubocop:disable-next Metrics/MethodLength
+      # rubocop:disable-next Metrics/MethodLength, Metrics/PerceivedComplexity
       def build(registry:, verb:, projected:, explicit:, passthrough: [], source_receiver: nil)
         args = projected.transform_keys(&:to_sym)
         unless explicit
@@ -99,6 +99,18 @@ 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.
+          return args unless target.entities.empty?
+
           inherited_receiver = source_receiver_for(target, source_receiver)
           return inherited_receiver ? args.merge(to: inherited_receiver) : args
         end
@@ -154,6 +166,26 @@ module Hecks
         raise UnknownVerb, "reaction target #{verb.inspect} does not resolve to an aggregate" unless aggregate
 
         *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.
+        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
+
+          return Target.new(aggregate: aggregate, entities: [], command: operation)
+        end
+
         owner = aggregate
         entities = entity_names.map do |entity_name|
           entity = owner.entities.find { |candidate| candidate.hecks_name == entity_name }
@@ -183,14 +215,49 @@ module Hecks
       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;
+      # 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.
       def source_receiver_for(target, source_receiver)
         return nil unless source_receiver
-        return nil unless target.entities.empty?
-        return nil if target.command.creates?
+        # `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.
+        return nil if target.entities.empty? && target.command.creates?
 
         source = source_receiver.transform_keys(&:to_sym)
         source_aggregate = source[:aggregate].to_s