hecks 1.1.0 → 1.3.0

data/lib/hecks/bluebook/behaviour/read_model.rb

@@ -14,14 +14,59 @@ module Hecks
 
         def query_name = Naming.snake(@name)
 
-        # WHICH GATHERED HEAD THE FILTERING APPLIES TO, so the read-model
-        # interpreter can ask this directly rather than re-deriving or
-        # re-checking it.
-        def filtered_head_name
-          return nil unless wheres.any? || order_by || limit || offset || authorization&.tenant ||
-                            @group_by.any? || count? || @median_field
-
-          @aggregate_heads.find { |head| head[:many] }&.fetch(:as)
+        # WHICH GATHERED HEADS THE FILTERING APPLIES TO (ADR 0055) — plural,
+        # since `where`/`order_by`/`limit`/`offset` can now each independently
+        # name a many-side head via `on:` once there's more than one. A read
+        # model with a single many-side head keeps the old reading: every
+        # UNTARGETED option (plus `group_by`/`count`/`median`, still
+        # single-head-only — ADR 0055) applies to it, same as before `on:`
+        # existed. With several many-side heads, only the ones actually named
+        # by a targeted option are eligible.
+        def filtered_head_names
+          many = @aggregate_heads.select { |head| head[:many] }
+          return [] if many.empty?
+
+          return single_filtered_head_name(many) if many.one?
+
+          targets = (wheres.map(&:target) + [order_by&.target, limit&.target, offset&.target]).compact.uniq
+          targets.filter_map { |target| many.find { |head| head[:aggregate] == target.to_s } }.map { |head| head[:as] }
+        end
+
+        # The pre-`on:` reading (ADR 0055), unchanged: with exactly one
+        # many-side head, every UNTARGETED option (plus `group_by`/`count`/
+        # `median`, still single-head-only) applies to it — split out only
+        # to keep `filtered_head_names` itself under this file's own
+        # complexity budget, not because the two questions differ in kind.
+        def single_filtered_head_name(many)
+          declared = wheres.any? || order_by || limit || offset || authorization&.tenant ||
+                     @group_by.any? || count? || @median_field
+          declared ? [many.first[:as]] : []
+        end
+
+        # THE where/order_by/limit/offset THAT APPLY TO ONE ELIGIBLE HEAD
+        # (ADR 0055) — a small view `Ports::Query::InMemory.execute` reads
+        # exactly the way it already reads a whole `Query`/`ReadModel`
+        # (`.wheres`/`.order_by`/`.limit`/`.offset`/`.null_semantics`), scoped
+        # to `head_as`'s own aggregate: an UNTARGETED option applies when
+        # `head_as` is the read model's ONE many-side head (the pre-`on:`
+        # reading, unchanged) ; a TARGETED one applies when its `target`
+        # resolves to `head_as`'s own aggregate.
+        FilteredOptions = Struct.new(:wheres, :order_by, :limit, :offset, :null_semantics)
+
+        def options_for(head_as)
+          many = @aggregate_heads.select { |head| head[:many] }
+          aggregate_name = @aggregate_heads.find { |head| head[:as] == head_as }&.fetch(:aggregate)
+          applies = lambda do |target|
+            target.nil? ? many.one? : target.to_s == aggregate_name
+          end
+
+          FilteredOptions.new(
+            wheres.select { |where| applies.call(where.target) },
+            order_by && applies.call(order_by.target) ? order_by : nil,
+            limit && applies.call(limit.target) ? limit : nil,
+            offset && applies.call(offset.target) ? offset : nil,
+            null_semantics
+          )
         end
       end
     end

data/lib/hecks/bluebook/dsl/aggregate_builder.rb

@@ -88,13 +88,18 @@ module Hecks
         end
 
         # `optional:` — matching `CommandBuilder#reference_to`'s own
-        # signature, which already had it; this one never forwarded it
-        # to `attribute_impl()` even though `attribute_impl()` itself
-        # already accepts it. A real gap: an aggregate that can point at
-        # ONE OF several targets (Item's own `personal_list_id`/
+        # signature, which already had it; this one used to never
+        # forward it to `attribute_impl()`/`relationship_attribute`
+        # even though those already accept it — closed in the same
+        # commit that added this comment (`optional: optional`, below).
+        # It was a real gap because an aggregate that can point at ONE
+        # OF several targets (Item's own `personal_list_id`/
         # `camping_list_id`, never both) needs each reference optional
         # on the aggregate's own persisted schema, not just as a
-        # command's input.
+        # command's input — real corpus use:
+        # `spec/fixtures/hop_chain.bluebook`'s own `Proposal` aggregate
+        # declares `reference_to Engagement, optional: true` at the
+        # aggregate head.
         # RENAMED FROM `reference_to` — item #13's full metaprogrammed
         # dispatch (slice 4b). Bootstrap-reachable (every core/attached
         # grammar chapter uses reference_to to describe itself), so also

data/lib/hecks/bluebook/dsl/read_model_builder.rb

@@ -54,6 +54,72 @@ module Hecks
           @includes << [Naming.demodulise(type), as]
         end
 
+        # `on:` (ADR 0055) — OVERRIDES of `QuerySpecification::Common::DSL`'s
+        # shared `where_impl`/`order_by_impl`/`limit_impl`/`offset_impl`,
+        # scoped to `ReadModelBuilder` alone rather than added to the shared
+        # module `Query` also mixes in: a plain `query` has no
+        # `aggregate_heads` at all, so `on:` there would be a silently-
+        # ignored no-op rather than a real answer. Overriding only here
+        # means a `Query`'s own `where(..., on: X)` gets Ruby's own loud
+        # `unknown keyword: :on` instead of quietly doing nothing.
+        #
+        # `on:` names the target by TYPE (`on: Character`), resolved the
+        # same way `reference_to`/`include` already resolve their own type
+        # argument (`Naming.demodulise`) — not by the include's own `as:`
+        # alias. A read model that `include`s the SAME type twice under two
+        # different `as:` has no way to say which one `on:` means today; no
+        # real corpus read model does this, so it's a real, deliberate scope
+        # limit (see ADR 0055), not an oversight.
+        #
+        # `*positional, on:, **rest` rather than a plain `(clauses, on: nil)`
+        # — found necessary, not stylistic, by reproducing the failure
+        # directly: `where(status: "disputed")` reaches here with its
+        # `status: "disputed"` captured as `**kwargs` (GenericDispatch's own
+        # `builder.send(calls, *args, **kwargs, &block)`), and Ruby stops
+        # auto-converting a bare `**hash` call into a plain positional Hash
+        # THE MOMENT a method declares any real keyword parameter — so a
+        # `(clauses, on: nil)` signature raised "wrong number of arguments
+        # (given 0, expected 1)" on every ordinary `where(field: value)`
+        # call, never reaching `on:` at all. `**rest` sidesteps this: Ruby
+        # still auto-splits `on:` into the declared keyword and gathers
+        # every OTHER key into `rest` regardless of how the caller wrote it.
+        #
+        # `QuerySpecification::Common::WhereClause` etc — FULLY QUALIFIED,
+        # not the bare names `dsl.rb`'s own shared `where_impl` gets away
+        # with. That file is lexically nested inside `Common` itself, so
+        # `WhereClause` resolves directly; this class is nested inside
+        # `Bluebook::DSL`, which has no lexical or ancestor path to
+        # `QuerySpecification::Common` at all — a bare `WhereClause` here
+        # falls through to `const_missing` and, mid-bluebook-load, that's
+        # `ConstShim`, which resolves it against the self-hosted grammar
+        # domain's OWN unrelated `WhereClause` construct instead (a `Module`,
+        # not this `Struct`) — found directly by reproducing "undefined
+        # method `new' for module WhereClause" against a real corpus load,
+        # not guessed.
+        def where_impl(*positional, on: nil, **rest)
+          raise ArgumentError, "wrong number of arguments (given #{positional.size}, expected 1)" if positional.size > 1
+
+          @wheres ||= []
+          target = resolve_target(on)
+          clauses = (positional.first || {}).merge(rest)
+          clauses.each do |field, value|
+            op, operand = split_comparator(value)
+            @wheres << QuerySpecification::Common::WhereClause.new(field: field, op: op, value: operand, target: target)
+          end
+        end
+
+        def order_by_impl(field, direction = :asc, on: nil)
+          @order_by = QuerySpecification::Common::OrderBy.new(field: field, direction: direction, target: resolve_target(on))
+        end
+
+        def limit_impl(value, on: nil)
+          @limit = QuerySpecification::Common::LimitSpec.new(value: value, target: resolve_target(on))
+        end
+
+        def offset_impl(value, on: nil)
+          @offset = QuerySpecification::Common::OffsetSpec.new(value: value, target: resolve_target(on))
+        end
+
         # NAMES which of the eligible head's own fields to nest its rows
         # under — one level per field, the leaf being that row with the
         # named fields removed (they're already spent, as the keys that
@@ -142,27 +208,70 @@ module Hecks
 
         private
 
-        # where/order_by/limit/offset/authorize's tenant all apply to exactly
-        # one collection — the single `include`d aggregate whose head is
-        # "many" (the "one" side, the reference target itself, is a single
-        # row; ordering, paging, or tenant-scoping one row means nothing). A
-        # read model with zero many-heads has nothing for them to filter ;
-        # one with several has no way to say WHICH of several unrelated
-        # collections a caller meant — so both refuse here rather than
-        # silently applying to an arbitrary one. `authorize`'s tenant counts
-        # here too — TenantScope enforces it against this same head, so an
-        # ambiguous target is exactly as unusable as it is for the others.
+        # where/order_by/limit/offset/authorize's tenant all apply to
+        # collections — the `include`d aggregates whose heads are "many"
+        # (the "one" side, the reference target itself, is a single row;
+        # ordering, paging, or tenant-scoping one row means nothing). ADR
+        # 0055 gave `where`/`order_by`/`limit`/`offset` an `on:` to name
+        # WHICH many-side collection they mean, so this asks two questions
+        # now instead of one:
+        #
+        #   1. Does every declared `on:` actually name a many-side included
+        #      aggregate? Checked regardless of how many many-side heads
+        #      exist — a typo refuses immediately, not only once ambiguity
+        #      would otherwise bite.
+        #   2. Is there still an UNTARGETED option declared (including
+        #      `authorize`'s own `tenant:`, which has no `on:` of its own —
+        #      a real, deliberate scope limit, see ADR 0055)? An untargeted
+        #      option still needs exactly one many-side head to mean
+        #      anything unambiguous — the ORIGINAL rule, unchanged, and
+        #      still worded the same way (`spec/runtime/
+        #      read_model_interpreter_spec.rb`'s existing refusal regex
+        #      still matches).
+        #
+        # A read model with several many-side heads is legal precisely when
+        # every declared option names one; a read model with a single
+        # many-side head is unaffected either way, `on:` or not.
         def seal_query_options
-          declared = @wheres&.any? || @order_by || @limit || @offset || @authorization&.tenant
-          return unless declared
+          many = Array(@aggregate_heads).select { |head| head[:many] }
 
-          many = Array(@aggregate_heads).count { |head| head[:many] }
-          return if many == 1
+          validate_declared_targets!(many)
+          return unless untargeted_option_declared?
+          return if many.size == 1
 
           raise Malformed,
-                "#{@name} declares where/order_by/limit/offset but includes #{many} many-side " \
+                "#{@name} declares where/order_by/limit/offset but includes #{many.size} many-side " \
                 "aggregates, not exactly one — these options apply to a single collection; " \
-                "name which one by including only it, or drop the options"
+                "name which one with `on:` (e.g. `where(field: value, on: Character)`), or drop the options"
+        end
+
+        # Question 1 of `seal_query_options`'s own two, split out to keep
+        # both under the same "one job per method" shape every OTHER seal in
+        # this file already holds to (each raises its own one Malformed, for
+        # its own one reason).
+        def validate_declared_targets!(many)
+          many_by_aggregate = many.to_h { |head| [head[:aggregate], head] }
+          declared_targets = Array(@wheres).map(&:target) + [@order_by&.target, @limit&.target, @offset&.target]
+
+          declared_targets.compact.uniq.each do |target|
+            next if many_by_aggregate.key?(target)
+
+            raise Malformed,
+                  "#{@name}'s `on: #{target}` doesn't name one of its own many-side included " \
+                  "aggregates (it includes #{many.map { |head| head[:aggregate] }.join(', ')} as " \
+                  "many-side heads)"
+          end
+        end
+
+        # Question 2 of `seal_query_options`'s own two — see that method's
+        # header. `authorize`'s own `tenant:` has no `on:` at all (ADR 0055's
+        # own documented scope limit), so it always counts as untargeted.
+        def untargeted_option_declared?
+          Array(@wheres).any? { |where| where.target.nil? } ||
+            (@order_by && @order_by.target.nil?) ||
+            (@limit && @limit.target.nil?) ||
+            (@offset && @offset.target.nil?) ||
+            @authorization&.tenant
         end
 
         # Same shape as `seal_query_options`, same reason — `group_by`
@@ -227,6 +336,12 @@ module Hecks
                 "pagination — use limit/offset instead"
         end
 
+        # `on:`'s own resolution (ADR 0055) — same demodulise `reference_to`/
+        # `include` already use for their own type argument. `nil` when `on:`
+        # is omitted, matching every other optional field's "absent, not
+        # false" reading in this file.
+        def resolve_target(on) = on && Naming.demodulise(on)
+
         def add_aggregate_head(type, name, many:)
           @aggregate_heads ||= []
           target = Naming.demodulise(type)

data/lib/hecks/bluebook/meta_validator/judge.rb

@@ -117,6 +117,28 @@ module Hecks
           offer(label) { @runtime.dispatch(verb, to: to, with: args(payload)) }
         end
 
+        # THE RECEIVER, SPELLED THE WAY A REAL CALLER ADDRESSES IT.
+        #
+        # `receiver` is an internal accumulator — it tracks the aggregate this
+        # walk is inside AND, once it crosses into a real entity-owned category
+        # (Member/Handler/Dispatch — S17, ADR 0026), every entity hop on top of
+        # it. But `Routing.envelope`/`parse_envelope_hash` do not want that
+        # shape restated when there is no entity to route to: a plain aggregate
+        # command is addressed by its bare id (`Facade::Handle#dispatch` — "to:
+        # @id" — and `CommandRequest`'s own header: "aggregate command: { to:
+        # "record-id", ... }"), never `{aggregate:, entities: []}` — that hash
+        # is the ENTITY route's own shape, degenerate with nothing in it.
+        #
+        # So THIS is the one place `receiver` turns into a `to:` value: bare
+        # when there is no entity hop (the overwhelming common case — every
+        # category but those three), the full envelope only when there
+        # genuinely is one.
+        def address(receiver)
+          return receiver[:aggregate] if receiver[:entities].empty?
+
+          receiver
+        end
+
         def judge!
           declare_node("Bluebook", @bluebook, nil, 0)
           detail_node("Bluebook", @bluebook, nil, 0)
@@ -384,7 +406,7 @@ module Hecks
             end
             next if payload.values.all?(&:nil?)
 
-            send_to("Bluebook::#{verb_for(plan, setter.verb)}", receiver[:aggregate], to: receiver, **payload)
+            send_to("Bluebook::#{verb_for(plan, setter.verb)}", receiver[:aggregate], to: address(receiver), **payload)
           end
         end
 
@@ -409,7 +431,7 @@ module Hecks
               end
 
               send_to("Bluebook::#{verb_for(plan, chosen.verb)}", "#{id}##{list_name}[#{index}]",
-                      to: receiver, **payload)
+                      to: address(receiver), **payload)
             end
           end
         end
@@ -430,7 +452,7 @@ module Hecks
 
         def sealers(plan, _category, receiver)
           id = receiver[:entities].last || receiver[:aggregate]
-          plan.sealers.each { |verb| send_to("Bluebook::#{verb_for(plan, verb)}", id, to: receiver) }
+          plan.sealers.each { |verb| send_to("Bluebook::#{verb_for(plan, verb)}", id, to: address(receiver)) }
         end
 
         # An aggregate's or an entity's attribute names its value object by TYPE,

data/lib/hecks/bluebook/model_check.rb

@@ -65,6 +65,40 @@ module Hecks
           [:unacknowledged_relationship, "FlagKeyReturn"],
           [:unknown_target_domain, "FlagKeyReturn"]
         ]
+        # QualityControl WAS the first domain in this corpus to trigger an
+        # `asks`/`tells` PORT OPERATION from a `policy`, and used to carry
+        # two entries here for it — both GONE now, not just quieted:
+        #
+        # `deaf_policy` (ClearOnPass, RefuseOnFail, RecordTheIssue,
+        # RecordTheRefusal) went first: `emitted_events` below now reads an
+        # outbound operation's `.answers`/`.refuses` the same way it already
+        # read a command's `.emits`, so `Clearance.SuitePassed`/`SuiteFailed`
+        # and `Ticket.IssueFiled`/`IssueFilingRefused` enter the known-emits
+        # set for real — the same fix `bin/qa_pr_check`'s own move to
+        # dispatching through the CI port (rather than `Clearance::Passed`/
+        # `Failed` directly) needed to make these two policies actually fire.
+        #
+        # `unknown_trigger` (FileWhenSubmitted, AskOnceMore) — BUG#23 — was
+        # never actually a `Naming`/`PolicyBuilder` defect, confirmed by
+        # tracing the real dispatch path rather than assuming the comment
+        # that used to sit here: `Naming.command_ref`'s bare-constant
+        # rewrite DOES leave `trigger Ticket::IssueTracker::File` (aggregate,
+        # port, operation) as "Ticket::IssueTracker.File", a leftover `::`
+        # past the aggregate — but `PolicyInterpreter#deliver` re-qualifies
+        # every trigger with this domain's own name before dispatch
+        # ("QualityControl::Ticket::IssueTracker.File"), and `Naming.
+        # split_verb` already folds that reintroduced `::` into the
+        # dot-joined tail correctly (fixed for `ReactionInvocation#
+        # resolve_target`, PR #520, predating this entry's own removal) —
+        # confirmed live: a real dispatch through `Ticket.Submit` fires
+        # `IssueFiled`/`TicketFiled` exactly as declared. The actual gap was
+        # entirely in THIS checker: `verbs_of` never enumerated a port
+        # operation as a triggerable verb at all, and `policy_findings`
+        # compared raw strings instead of `Naming.split_verb` triples the
+        # way `handler_findings`'s own `unknown_dispatch` check already does
+        # (BUG#6). Fixed with `port_verbs_of`/`triggerable_verbs`, scoped
+        # entirely to this file — no change to `Naming` or `PolicyBuilder`
+        # was needed or made.
       }.freeze
 
       module_function
@@ -215,7 +249,12 @@ module Hecks
 
       def saga_findings(bluebook, process_manager)
         emitted = emitted_events(bluebook)
-        verbs   = verbs_of(bluebook)
+        # (domain, aggregate, command) TRIPLES, not raw strings — see
+        # `handler_findings`'s own comment on the dispatch side for why:
+        # `Naming.split_verb` is what makes an entity verb's two legitimate
+        # spellings (`Naming.command_ref`'s own `::`-then-`.` rewrite vs.
+        # `verbs_of`'s own all-`.` one) compare equal.
+        verbs   = verbs_of(bluebook).map { |verb| Naming.split_verb(verb) }
         reached = pm_reachable_states(process_manager, emitted)
 
         findings = []
@@ -266,16 +305,38 @@ module Hecks
         end
 
         handler.dispatches.each do |dispatch|
-          # SAME-DOMAIN, same as `SagaInterpreter#qualified` — a dispatch
-          # naming no domain at all (the ordinary shape a bare command
-          # constant now produces, S6) means THIS one, and is compared
-          # against `verbs_of`'s own fully-qualified spelling qualified
-          # the identical way, not left bare to miss it on a technicality.
-          qualified = if dispatch.command_name.include?("::")
-                        dispatch.command_name
-                      else
-                        "#{bluebook.name}::#{dispatch.command_name}"
-                      end
+          # ALWAYS THIS DOMAIN — same fix, same reason, as `SagaInterpreter
+          # #qualified` (BUG#6). This used to guess: a dispatch whose own
+          # `command_name` still carried a leftover `::` after `Naming.
+          # command_ref`'s own rewrite was read as "already qualified" and
+          # left alone — the exact same string-shape ambiguity that
+          # `SagaInterpreter#qualified`'s own comment explains at length
+          # (a same-domain entity command reference and a genuinely
+          # cross-domain one are textually indistinguishable after that
+          # rewrite). Confirmed against the entire corpus, same as that
+          # fix: no saga anywhere ever dispatches genuinely cross-domain,
+          # so this checker now qualifies exactly the way the runtime
+          # actually dispatches — unconditionally against `bluebook.name`
+          # — instead of maintaining its own, independently-wrong copy of
+          # the same guess.
+          #
+          # COMPARED AS A TRIPLE, NOT A STRING — `Naming.command_ref`'s
+          # own rewrite of an entity reference (`Manifest::Slot::Fill`)
+          # collapses to "Manifest::Slot.Fill" (`::` between aggregate and
+          # entity, `.` before the command); `verbs_of`'s own entity
+          # spelling, below, joins aggregate/entity/command all with `.`
+          # instead (matching `fuzzing/sequence_generator/catalog.rb`'s own
+          # independent convention, its comment's own "the same spelling"
+          # claim). Both are legitimate, and `Naming.split_verb` already
+          # parses either to the identical (domain, aggregate, command)
+          # triple (its own comment: "past the already-resolved domain
+          # boundary, any leftover `::` is unambiguous... folding it into
+          # the dot-joined tail") — the same reading `ReactionInvocation.
+          # resolve_target` relies on at runtime. A bare string `include?`
+          # would falsely flag every entity dispatch as unknown_dispatch
+          # even once correctly domain-qualified, comparing two spellings
+          # of the same verb as though they were different ones.
+          qualified = Naming.split_verb("#{bluebook.name}::#{dispatch.command_name}")
           next if verbs.include?(qualified)
 
           findings << Finding.new(kind: :unknown_dispatch, severity: :error, subject: process_manager.name,
@@ -366,9 +427,27 @@ module Hecks
         # `trigger` is spelled "Aggregate.Command" (or "Entity.Command" one
         # level down), completed to an FQN by PolicyInterpreter#deliver as
         # "#{domain}::#{trigger_command}" — the same join `verbs_of` builds
-        # independently, so the two spellings have to be compared as FQNs,
-        # never as bare command names.
-        unless verbs_of(bluebook).include?("#{bluebook.name}::#{policy.trigger_command}")
+        # independently, so the two spellings have to be compared as FQNs.
+        #
+        # COMPARED AS A TRIPLE, NOT A STRING — `handler_findings`'s own
+        # `unknown_dispatch` check (BUG#6) already applies this fix for a
+        # saga's dispatch; a policy's `trigger` needed the identical one. A
+        # policy triggering an `asks`/`tells` PORT OPERATION (`Aggregate::
+        # Port::Operation`, three colon-joined segments — `Naming.command_ref`'s
+        # bare-constant rewrite turns this into "Aggregate::Port.Operation",
+        # a leftover `::` past the aggregate) is a real, WORKING dispatch —
+        # `PolicyInterpreter#deliver` qualifies it with this domain's own
+        # name before `Naming.split_verb` ever sees it, and `split_verb`
+        # already folds that leftover `::` into the dot-joined tail
+        # correctly (fixed for `ReactionInvocation#resolve_target`, PR
+        # #520) — but this check compared raw strings against `verbs_of`,
+        # which never enumerated port operations at all, so it reported
+        # every port-operation trigger as unknown regardless. `triggerable_
+        # verbs` now includes both, and both sides are parsed through
+        # `Naming.split_verb` before comparing, the same reading
+        # `resolve_target` relies on at runtime.
+        qualified = Naming.split_verb("#{bluebook.name}::#{policy.trigger_command}")
+        unless qualified && triggerable_verbs(bluebook).include?(qualified)
           findings << Finding.new(kind: :unknown_trigger, severity: :error, subject: policy.name,
                                   message: "trigger #{policy.trigger_command.inspect} resolves to no command " \
                                            "this domain declares")
@@ -464,15 +543,38 @@ module Hecks
       # the fixtures under spec/fixtures/model_check/ do, having no
       # hecksagon at all) simply finds none, which is correct : nothing
       # can be deaf to an event that isn't even wired up yet.
+      #
+      # AN OUTBOUND OPERATION (`asks`) EMITS THROUGH A DIFFERENT DOOR — it
+      # declares no `.emits` at all (`PortOperationBuilder#refuse_wrong_
+      # words!` refuses one that tries), naming its two real endings
+      # `.answers`/`.refuses` instead (`PortOperation#initialize`). Reading
+      # only `.emits` left every `asks`'s own two events invisible to this
+      # method — real, live events a policy genuinely reacts to
+      # (`Clearance.SuitePassed`/`SuiteFailed`, `Ticket.IssueFiled`/
+      # `IssueFilingRefused`), reported as `deaf_policy` findings until this
+      # read both. `.compact` because an INBOUND operation's `.answers`/
+      # `.refuses` are always nil (there is no channel back to tell), which
+      # would otherwise seed every emitted-events set with a stray nil.
       def emitted_events(bluebook)
         aggregate_emits = bluebook.aggregates.flat_map do |aggregate|
           aggregate.commands.map(&:emits) +
             aggregate.entities.flat_map { |entity| entity.commands.map(&:emits) } +
-            aggregate.ports.flat_map { |port| port.operations.map(&:emits) }
+            port_operation_events(aggregate.ports)
         end
-        chapter_emits = bluebook.ports.flat_map { |port| port.operations.map(&:emits) }
+        chapter_emits = port_operation_events(bluebook.ports)
+
+        (aggregate_emits + chapter_emits).flatten.compact.uniq
+      end
 
-        (aggregate_emits + chapter_emits).flatten.uniq
+      # ONE OPERATION, EITHER OF ITS OWN SOURCES OF EVENTS — an inbound
+      # `tells` names its own via `.emits`; an outbound `asks` has none
+      # (`PortOperationBuilder#refuse_wrong_words!` refuses one that
+      # tries) and names its two real endings `.answers`/`.refuses`
+      # instead. Pulled out of `emitted_events` above purely to keep that
+      # method's own branching low enough to read at a glance — every
+      # port, aggregate-owned or chapter-level, asks this the same way.
+      def port_operation_events(ports)
+        ports.flat_map { |port| port.operations.flat_map { |op| [*op.emits, op.answers, op.refuses] } }
       end
 
       # Fully-qualified, the same spelling DispatchSpec#command_name
@@ -490,6 +592,35 @@ module Hecks
         end
       end
 
+      # AN AGGREGATE-OWNED PORT OPERATION IS A TRIGGERABLE VERB TOO —
+      # `ReactionInvocation#resolve_target`'s own port-operation branch
+      # resolves one by the exact same two-segment tail shape ("Aggregate::
+      # Port.Operation", the aggregate then the port then the operation,
+      # dot-joined past the domain) an entity command uses, checked first,
+      # same order `Dispatcher#dispatch` already resolves a live verb in.
+      # Only an aggregate's OWN ports (`aggregate.ports`) are in scope here
+      # — a policy's `trigger` always names one aggregate, never a chapter-
+      # level port with no owner to address through.
+      def port_verbs_of(bluebook)
+        bluebook.aggregates.flat_map do |aggregate|
+          aggregate.ports.flat_map do |port|
+            port.operations.map do |operation|
+              "#{bluebook.name}::#{aggregate.hecks_name}.#{port.name}.#{operation.hecks_name}"
+            end
+          end
+        end
+      end
+
+      # EVERY TRIGGERABLE VERB, AS A TRIPLE — `verbs_of` (ordinary/entity
+      # commands) plus `port_verbs_of` (port operations), each parsed
+      # through `Naming.split_verb` so a caller never has to compare two
+      # spellings of the same verb as strings (see `policy_findings`'s own
+      # `unknown_trigger` check for why that comparison has to happen this
+      # way, not as `include?` on a raw string).
+      def triggerable_verbs(bluebook)
+        (verbs_of(bluebook) + port_verbs_of(bluebook)).to_set { |verb| Naming.split_verb(verb) }
+      end
+
       def bare(event) = event.to_s.split("::").last
     end
   end

data/lib/hecks/forms/field_shape.rb

@@ -1,4 +1,5 @@
 require_relative "../bluebook/attribute"
+require_relative "../naming"
 require_relative "value_object_shape"
 
 module Hecks
@@ -36,10 +37,11 @@ module Hecks
         # genuinely dotted path ("amount.cents") drops everything before
         # the last ".".
         segment = text.to_s.split(".").last.to_s
-        words = segment.split("_")
-        return segment if words.empty?
+        return segment if segment.empty?
 
-        ([words.first.capitalize] + words.drop(1)).join(" ")
+        # The word split itself is `Naming.words`' now — the one
+        # humanizer, shared with the glossary projection.
+        Naming.words(segment)
       end
 
       # The full dotted path, each segment humanized and joined with