hecks 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d66cdbdb775a92f3cfcf3f626637cffd6fb81915d7edbcccfe21e1b7c980606
-  data.tar.gz: a43786075ea299d26d6d1f23075cf2176fdad15b7efa235234c4a6e321ec15f3
+  metadata.gz: b85a8382bb201f9ab54417b3535d8fe1ede57c842f627e32a2ff75d7f2dd6618
+  data.tar.gz: e4852fd6b22145bec8a215e4c46fc6347527f7bd05811ff7da780e74dc24fe1d
 SHA512:
-  metadata.gz: ac3883e9e6ebeef723718dfa39785d2dcdd0e57e613f6ca21a9519040eb11278f22eedbe597965d1b28e3dfa08b98ac2d0a989686cd7b8aec0d8d97dd476acec
-  data.tar.gz: f610074205ca1a39121169ef02109445b60ca66bf517c1a8351e8c761a1863fccfe0f9b41075fa00cc8225c017c82eefdb47c38566469fe378d0879aec115860
+  metadata.gz: a538ddbe90fed2ccfa8c066f00777699b0eadade3c6523e6fbf5f62c19385ab7ace8e2c8de6fabafffce46abbefd36642401f6e5f23696127445378e95d98aad
+  data.tar.gz: e22574943d4246998ba9121c0c84d7b39ec944416066ad881f144f166a09deb5c1a1fbb8b6c8378084b89856ed9a4e5bfd9c66a3cd6d07fa9a9a21eee77d63fc

data/lib/hecks/adapters/driven/heki/journal.rb

@@ -17,8 +17,65 @@ module Hecks
           end
         end
 
+        # An EXPLICIT, opt-in maintenance operation — never run
+        # automatically after an ordinary save/delete. Heki's journal is
+        # not a disposable write-ahead log: it is this adapter's own
+        # answer to `entries`, and `entries` is a real port contract
+        # (`Ports::Persistence::AppendOnly`'s own required-methods list)
+        # read in full, forever, by `Ports::Projection::Worker#catch_up!`
+        # and `Registry#projection_current?` to catch a projection up to
+        # its authoritative source, and by `bin/history` to show "every
+        # journal entry a domain's append-only adapters hold" — the same
+        # contract Postgres/Sqlite/D1 uphold by way of a journal TABLE
+        # that is never pruned. A real example (`examples/banking`,
+        # `persisted_by("Heki")` + `projected_by("SqliteProjection")`)
+        # depends on this today. Compacting throws that full history away
+        # for whatever happened before the call — correct only for an
+        # aggregate nothing ever projects from; callers (`bin/
+        # heki_compact`) are responsible for confirming that first.
+        #
+        # Crash-safety ordering: `write` below is the exact same
+        # temp-file, fsync, atomic-rename sequence `save`/`delete`
+        # already use — the snapshot it produces is confirmed durably on
+        # disk before this method ever touches the journal. Only once
+        # that succeeds does `truncate_journal!` run. A crash between the
+        # two leaves old (now fully redundant) journal lines in place;
+        # replaying them again over the fresh snapshot on the next boot
+        # is idempotent — the same value gets set again, never a wrong
+        # one — so nothing is lost, just a little wasted replay work
+        # once. A crash before `write` completes leaves the journal
+        # fully intact and the prior snapshot untouched, exactly today's
+        # existing crash-recovery guarantee.
+        def compact!
+          with_lock do
+            current = replay_journal(read_snapshot)
+            write(current)
+            truncate_journal!
+            @store = current
+          end
+        end
+
         private
 
+        def truncate_journal!
+          return unless File.exist?(@journal_path)
+
+          # A single `truncate(0)` syscall on an already-open file
+          # descriptor — the file's length changes atomically at the
+          # filesystem level, so there is no "half truncated" state to
+          # observe even under a crash mid-call. `fsync` below makes
+          # that change durable before this method returns; without it
+          # a crash could still leave the old (harmless-to-replay)
+          # content on disk after a normal return, which is fine per
+          # the crash-safety note above, but the durable case is the
+          # one actually worth returning success for.
+          File.open(@journal_path, "r+b") do |file|
+            file.truncate(0)
+            file.flush
+            file.fsync
+          end
+        end
+
         def replay_journal(records)
           return records unless File.exist?(@journal_path)
 

data/lib/hecks/adapters/driven/postgres_era.adapter

@@ -14,4 +14,9 @@ Hecks.adapter "PostgresEra" do
   field :database
   field :role
   field :schema
+  # `allow_superuser true` — the explicit, on-the-record opt-in to boot
+  # over a connection whose role is a Postgres superuser or carries
+  # BYPASSRLS, which the era write-fence (row-level security) cannot
+  # bite. Refused by default; see `Lineage#check_fence_applies!` (BUG#24).
+  field :allow_superuser
 end

data/lib/hecks/adapters/driving/github_webhook.rb

@@ -0,0 +1,145 @@
+require "openssl"
+require "json"
+require "rack"
+
+module Hecks
+  module Adapters
+    # THE DRIVING SIDE — code an OUTSIDE caller reaches IN through,
+    # rather than code the domain reaches OUT through. Every existing
+    # file under `adapters/driven/` is the latter: a store or reader a
+    # `persisted_by`/`port` binding resolves TO, called BY this
+    # framework's own runtime. Nothing under this repository has ever
+    # been the mirror image before — code that receives a request FROM
+    # the outside world and turns it into a dispatch — so this is the
+    # first entry, and the directory itself is new.
+    module Driving
+      # A GITHUB WEBHOOK RECEIVER, TRANSPORT ONLY — the same split
+      # `Hecks::Adapters::GithubChecks` (qa/adapters/github_checks.rb,
+      # this class's own PULL-side sibling) already draws for itself:
+      # THIS file owns proving a request really came from GitHub and
+      # unwrapping GitHub's own webhook envelope (`X-GitHub-Event`, the
+      # JSON body, GitHub's own automatic `ping` check) — never which
+      # commands to dispatch about what it finds inside. That is exactly
+      # as domain-specific as `GithubChecks#run` turning `check-runs`
+      # JSON into green-or-raise, and lives exactly where that class's
+      # own header explains such logic belongs: outside this library,
+      # in `qa/adapters/github_ci_webhook.rb`, the subclass of this file
+      # that actually knows what a `QualityControl::Clearance` is.
+      #
+      # A PLAIN RACK APP (`#call(env)`) — no Sinatra, no Rails — the same
+      # shape `Hecks::Forms::App` (lib/hecks/forms/app.rb) already
+      # established for the one other HTTP-facing surface this library
+      # ships. `rack` is a LAZY Gemfile dependency for exactly the reason
+      # that file's own header gives: this file is never required by
+      # `require "hecks"` (nothing under `adapters.rb`'s own eager
+      # `adapters/driven` load names it — see that file's own header),
+      # so a project that never mounts a driving adapter never needs
+      # `rack` installed, the same "opt in by requiring the file at all"
+      # contract `hecks/forms.rb` already has for `Forms::App`.
+      #
+      # SUBCLASS RESPONSIBILITY: implement `#handle_event(event, action,
+      # payload)`, returning `[http_status, response_body_hash]`. Called
+      # ONLY after the signature has verified and the body has parsed as
+      # JSON — a subclass never has to re-check either. `event` is
+      # GitHub's own `X-GitHub-Event` header value ("check_suite",
+      # "check_run", "pull_request", ...); `action` is the payload's own
+      # top-level `"action"` field when it has one (GitHub's webhooks
+      # nearly all carry one — "completed", "requested", "opened", ...)
+      # and nil when it does not. `ping` — GitHub's own automatic
+      # connectivity check, sent once when a webhook is first saved in
+      # repository settings — is answered here and never reaches a
+      # subclass at all; there is nothing domain-specific to decide
+      # about it.
+      class GithubWebhook
+        # REFUSED, LOUDLY — the same shape a domain refusal already takes
+        # everywhere else in this codebase (`Runtime::DOMAIN_REFUSALS`,
+        # `Forms::App`'s own `{error:, message:}` JSON body for a bad
+        # command). A request that cannot prove it came from GitHub gets
+        # a real 401 and a named reason, never a silent 200 that would
+        # let a forged "CI passed" payload regress nothing while looking
+        # exactly like success in a log nobody re-reads.
+        class InvalidSignature < StandardError; end
+
+        # THE BODY DID NOT EVEN PARSE — distinct from a signature refusal:
+        # this body genuinely came from whoever signed it (checked
+        # FIRST, before parsing ever runs — see `#call`), and simply
+        # is not JSON. Still refused, never guessed at.
+        class MalformedPayload < StandardError; end
+
+        SIGNATURE_HEADER = "HTTP_X_HUB_SIGNATURE_256".freeze
+        EVENT_HEADER     = "HTTP_X_GITHUB_EVENT".freeze
+
+        # `secret:` HAS NO DEFAULT, ON PURPOSE — the same rule
+        # `GoogleAuthentication`'s own header states for its own
+        # `ENV.fetch`, restated here because the consequence is worse for
+        # a webhook: an unverified signature check is not "half
+        # configured", it is NO verification at all, silently accepting
+        # anything claiming to be GitHub. A caller passes the real
+        # secret explicitly — from `ENV.fetch("GITHUB_WEBHOOK_SECRET")`
+        # or wherever it keeps one — rather than this class reaching into
+        # the environment itself and hiding that requirement inside a
+        # default.
+        def initialize(secret:)
+          raise ArgumentError, "no webhook secret configured" if secret.to_s.empty?
+
+          @secret = secret
+        end
+
+        def call(env)
+          request = Rack::Request.new(env)
+          return respond(405, error: "MethodNotAllowed", message: "POST only") unless request.post?
+
+          body = request.body.read
+          verify_signature!(request, body)
+
+          event = request.get_header(EVENT_HEADER)
+          return respond(200, ok: true, event: "ping") if event == "ping"
+          return respond(400, error: "MissingEvent", message: "no #{EVENT_HEADER} header") if event.to_s.empty?
+
+          payload = parse_json(body)
+          status, result = handle_event(event, payload["action"], payload)
+          respond(status, result)
+        rescue InvalidSignature => e
+          respond(401, error: "InvalidSignature", message: e.message)
+        rescue MalformedPayload => e
+          respond(400, error: "MalformedPayload", message: e.message)
+        end
+
+        private
+
+        # CONSTANT-TIME COMPARE, NOT `==`. A byte-by-byte `==` returns
+        # the moment it finds the first mismatching byte, so how LONG
+        # that took leaks how many leading bytes of a forged signature
+        # were already right to anyone timing the response — GitHub's
+        # own webhook documentation calls this out by name and recommends
+        # exactly the constant-time compare `Rack::Utils.secure_compare`
+        # already gives for free, reused rather than hand-rolled.
+        def verify_signature!(request, body)
+          header = request.get_header(SIGNATURE_HEADER)
+          raise InvalidSignature, "missing #{SIGNATURE_HEADER.sub('HTTP_', '').tr('_', '-')} header" if header.to_s.empty?
+
+          digest   = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), @secret, body)
+          expected = "sha256=#{digest}"
+          return if Rack::Utils.secure_compare(expected, header)
+
+          raise InvalidSignature,
+                "signature does not match — refusing a payload that cannot be proven to be GitHub's own"
+        end
+
+        def parse_json(body)
+          JSON.parse(body)
+        rescue JSON::ParserError => e
+          raise MalformedPayload, e.message
+        end
+
+        def handle_event(event, action, payload)
+          raise NotImplementedError, "#{self.class} must implement #handle_event(event, action, payload)"
+        end
+
+        def respond(status, body)
+          [status, { "content-type" => "application/json" }, [JSON.generate(body)]]
+        end
+      end
+    end
+  end
+end

data/lib/hecks/behaviors/expectations.rb

@@ -194,11 +194,24 @@ module Hecks
       # mixed facts into the strict envelope — identities lifted into
       # `to:`, declared facts into `with:` — so a behaviors dispatch now
       # goes through the exact same separation a policy's projection
-      # does. A verb that resolves to no command (a port operation —
-      # "Pizzas::Order.PaymentGateway.Receive") keeps the loose
-      # passthrough: its own input already spells the port form's
-      # `to:`/`with:`, which the dispatcher's port branch reads directly.
+      # does. A verb that names a port operation (checked explicitly,
+      # below — "Pizzas::Order.PaymentGateway.Receive") keeps the loose
+      # passthrough instead: its own input already spells the port
+      # form's `to:`/`with:`, which the dispatcher's port branch reads
+      # directly, and `ReactionInvocation.build`'s explicit envelope
+      # expects a command's own declared attributes at the top level,
+      # not a port operation's already-wrapped `to:`/`with:` shape.
+      #
+      # THIS USED TO RELY ON `resolve_target` RAISING `UnknownVerb` for
+      # any port-operation verb — true only so long as nothing else ever
+      # asked it to resolve one. Now that a `policy` can legitimately
+      # `trigger` a port operation (`ReactionInvocation#resolve_target`'s
+      # own port-operation branch), that raise is gone, so this checks
+      # for a port operation directly instead of leaning on a refusal
+      # that no longer happens.
       def dispatch_command(runtime, verb, args)
+        return runtime.dispatch(verb, **args) if port_operation?(runtime, verb)
+
         invocation = begin
           Runtime::ReactionInvocation.build(registry: runtime.registry, verb: verb,
                                             projected: args, explicit: true)
@@ -214,6 +227,21 @@ module Hecks
         end
       end
 
+      # THE SAME "Head.Rest" SHAPE `Dispatcher#dispatch` AND
+      # `ReactionInvocation#resolve_target` BOTH ALREADY CHECK — a bare
+      # domain/aggregate lookup plus a port-name lookup, no command
+      # resolution needed since all this asks is whether one exists.
+      def port_operation?(runtime, verb)
+        domain, aggregate_name, command_path = Naming.split_verb(verb)
+        return false unless command_path
+
+        aggregate = runtime.registry.bluebook(domain)&.aggregate(aggregate_name)
+        return false unless aggregate
+
+        head, rest = command_path.split(".", 2)
+        rest && !!aggregate.port(head)
+      end
+
       def run_query(test, runtime, verb)
         rows = runtime.query(verb, **test.input)
 

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

@@ -11,9 +11,33 @@ module Hecks
         # what it acts for, and `identity_attribute` is how that is found.
         def references = nil
 
+        # NEVER a creating command — a port operation always acts on an
+        # aggregate that already exists (`operation.to`/`identity_attribute`
+        # both name where its RECEIVER comes from, never a birth). Answered
+        # explicitly, not derived from `references` the way `Command
+        # #creates?` is (`references.nil?` would read every operation as
+        # creating, since `references` above is unconditionally nil) —
+        # needed so `ReactionInvocation#source_receiver_for` can call
+        # `target.command.creates?` on a port operation the same way it
+        # already does on an ordinary command, and correctly lift a
+        # same-aggregate policy's own Event.id as the operation's receiver.
+        def creates? = false
+
         def identity_attribute(owner_name)
           @attributes.find { |attribute| attribute.reference? && attribute.type.target_name == owner_name.to_s }
         end
+
+        # THE SAME READING `Command#addressing_key_for` gives, minus its
+        # self-addressing branch — a port operation's `references` is
+        # unconditionally nil (above), so it never means "this verb is
+        # declared ON the very aggregate it acts on" the way a command's
+        # does; a port operation's only path back to its owner is a real,
+        # declared reference-typed attribute, which is exactly what
+        # `identity_attribute` already finds. Needed for the identical
+        # reason `Command#addressing_key_for` is: `ReactionInvocation
+        # #aggregate_aliases` calls it on whatever `target.command` holds,
+        # a `PortOperation` now included since a policy can trigger one.
+        def addressing_key_for(aggregate_name) = identity_attribute(aggregate_name)&.name
       end
 
       # WHAT A PORT DOES — one finder over its declared operations.

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