hecks 1.3.0 → 1.5.0

data/lib/hecks/runtime/query_interpreter.rb

@@ -15,27 +15,43 @@ 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.
     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.
+      #
+      # @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
+      # @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
       def call(domain, aggregate, query_name, args)
         return entity_rows(domain, aggregate, query_name, args) if query_name.include?(".")
 
         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 +67,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)` 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
+          # 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,21 +82,33 @@ 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.
+      #
+      # @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
+      # @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
       def reference_call(domain, aggregate, query_name, args)
         return entity_rows(domain, aggregate, query_name, args) if query_name.include?(".")
 
@@ -95,22 +123,22 @@ 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
-        # any query answered here, not just come out reversed.
+        # 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.
         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 +148,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 +156,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 +205,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 +214,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 +243,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.
@@ -258,12 +277,12 @@ module Hecks
       end
 
       # The comparator table itself lives in
-      # QuerySpecification::Common::Comparison. This method and
-      # 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
-      # path: the registry is instance state rather than an argument.
+      # 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.
       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
@@ -276,40 +295,40 @@ module Hecks
 
       # `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
+      # 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
+      # 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,
+      # `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
+      # 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
+      # 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
+      # `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
+      # 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`
+      # 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
+      # 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.
       #

data/lib/hecks/runtime/reaction_invocation.rb

@@ -6,10 +6,10 @@ 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. Reaction declarations
-    # historically selected both through one `with:` map, so this is the one
-    # compatibility seam that separates receiver identities from facts after
-    # resolving the declaration and before re-entering the dispatcher.
+    # 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.
     module ReactionInvocation
       Target = Struct.new(:aggregate, :entities, :command, keyword_init: true)
       # :facts, not :values — Struct.new already defines #values (every
@@ -19,10 +19,17 @@ module Hecks
 
       module_function
 
-      # The holding IR historically represented both an omitted projection and
-      # an explicitly empty `with: {}` as the same empty array. Builders now
-      # preserve declaration presence off-wire; reconstructed/legacy IR falls
-      # back to the old non-empty reading.
+      # 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.
+      #
+      # @param declaration [Bluebook::Policy, Bluebook::DispatchSpec] the reacting
+      #   declaration to check
+      # @return [Boolean] true if the declaration names an explicit `with:` projection
       def projection_declared?(declaration)
         if declaration.instance_variable_defined?(:@projection_declared)
           declaration.instance_variable_get(:@projection_declared)
@@ -31,11 +38,27 @@ 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.
+      #
+      # @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 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
       def resolve_mapping(with_spec:, scopes:, bindings: {}, label: "reaction")
         normalized_bindings = bindings.transform_keys(&:to_sym)
         normalized_scopes = scopes.map do |scope|
@@ -49,7 +72,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 +83,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 +103,34 @@ 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, 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
       def build(registry:, verb:, projected:, explicit:, passthrough: [], source_receiver: nil)
         args = projected.transform_keys(&:to_sym)
         unless explicit
@@ -99,7 +144,7 @@ module Hecks
           rescue UnknownVerb
             return args
           end
-          # AN ENTITY TARGET HAS NO SHAPE THIS BRANCH CAN BUILD — an
+          # 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
@@ -167,13 +212,13 @@ 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
+        # 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`
+        # 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-
@@ -215,37 +260,37 @@ 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`
+      # 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
+      # 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
+      # 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
+      # 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
+      # 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
+      # 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
-        # `target.command.creates?` ALONE MISREADS EVERY ENTITY COMMAND —
+        # `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?`
+        # 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
@@ -253,7 +298,7 @@ module Hecks
         # 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
+        # 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.