hecks 1.2.0 → 1.4.0

data/lib/hecks/bluebook/model_check.rb

@@ -1,17 +1,19 @@
+require "hecks/vocabulary"
+
 module Hecks
   module Bluebook
     # Lightweight formal methods over the IR — the same family as TLA+/
     # Alloy/P: every lifecycle is a declared finite state machine and
-    # every process manager a declared protocol, and BOTH are already
-    # data, not code, so they can be MODEL-CHECKED rather than merely
+    # every process manager a declared protocol, and both are already
+    # data, not code, so they can be model-checked rather than merely
     # executed. Static analysis only — no bluebook boots twice, no
     # runtime is touched — over what meta_validator/judge.rb and the
     # builders' own `validate!` methods leave uncovered (an undeclared
     # transition target, a dispatch to nowhere, a compensation nothing
     # can ever reach).
     #
-    # THE RARE PROPERTY THIS RESTS ON: the model IS the implementation.
-    # A checker over TLA+ verifies a SPEC a human keeps in sync with
+    # **The rare property this rests on**: the model is the implementation.
+    # A checker over TLA+ verifies a spec a human keeps in sync with
     # code by hand ; this verifies the same IR the runtime dispatches
     # against, so there is no second copy to drift.
     module ModelCheck
@@ -19,8 +21,8 @@ module Hecks
         def to_s = "#{severity.to_s.upcase.ljust(7)} #{kind.to_s.ljust(20)} #{subject}  —  #{message}"
       end
 
-      # A FINDING SHIPPED, NOT SILENCED — the coverage-gate idiom, empty
-      # allowlists enforced BOTH directions (spec/model_check_spec.rb holds
+      # **A finding shipped, not silenced** — the coverage-gate idiom, empty
+      # allowlists enforced both directions (spec/model_check_spec.rb holds
       # this exact table: an error the checker reports and this does not
       # name is a regression, an entry the checker no longer reports is
       # stale and must be deleted). bin/model_check reads this same
@@ -29,42 +31,73 @@ module Hecks
       # "banking"/ExternalSettlement — found on the first real run:
       # ExternalSettlement declares `ends_on "ExternalTransferSent"`, and
       # ExternalTransfer.Send genuinely emits it — the event is real, and
-      # the AGGREGATE reaches "sent" (its own, separate lifecycle) — but
-      # the SAGA'S protocol has no `on "ExternalTransferSent"` handler, so
+      # the aggregate reaches "sent" (its own, separate lifecycle) — but
+      # the saga's protocol has no `on "ExternalTransferSent"` handler, so
       # its own `state "sent"` is unreachable through the chain the
       # checker walks, and the saga's own bookkeeping (saga_log, ends_on)
       # never closes it. Real domain activity is unaffected; the saga's
-      # OWN tracking of it is not. Left named rather than redesigning a
+      # own tracking of it is not. Left named rather than redesigning a
       # corpus fixture that is not this checker's to redesign.
       # S7, ADR 0025 — the ExternalSettlement finding this used to
-      # allowlist is GONE, not just quieted: its "sent" state was a
+      # allowlist is gone, not just quieted: its "sent" state was a
       # `state "x"` line never named by any handler's own from:/to:, a
-      # pure declaration-drift artifact. States are DERIVED from the
+      # pure declaration-drift artifact. States are derived from the
       # transitions that name them now (ProcessManagerBuilder#derived_
       # states), so a state nothing ever transitions into or out of no
       # longer exists to be unreachable — the finding this allowlisted
       # cannot occur any more, by construction.
       #
-      # "banking"/NotifyOnClosure, FlagKeyReturn — real, confirmed
-      # findings, not bugs to fix. `across "Notifications"` names a
-      # domain that does not exist anywhere in this repo — no
-      # Notifications bluebook, no hecksagon, nothing to `uses_framework`
-      # or `subscribe` to. This is deliberate: `spec/runtime/policy_spec.
-      # rb` (a test literally named "records a reaction it cannot
-      # deliver rather than swallowing it") and `lib/hecks/runtime/
-      # errors.rb`'s own `UnknownVerb` comment both treat "target domain
-      # not loaded" as the EXPECTED outcome for it — Notifications is
-      # used on purpose to exercise the undelivered-reaction runtime
-      # path, not left half-built. There is no real `subscribe` line to
-      # add (no event of Notifications' own to name) and no real domain
-      # to point `uses_framework` at.
+      # "banking"/NotifyOnClosure, FlagKeyReturn — gone from here, moved
+      # to banking. `across "Notifications"` names a domain that does not
+      # exist anywhere in this repo, deliberately (it exercises the
+      # undelivered-reaction runtime path — `spec/runtime/policy_spec.rb`,
+      # "records a reaction it cannot deliver rather than swallowing it").
+      # That expectation is now declared on the two policies themselves —
+      # `across "Notifications", expect_undelivered: true` — and
+      # `expected_undelivered_findings` below holds it in both directions:
+      # the unknown-target and unacknowledged-relationship findings are
+      # expected, and a declaration whose target turns out reachable is a
+      # `stale_undelivered_expectation` error. A domain's own allowance
+      # lives in its own source, never in a core table keyed by its name.
+      #
+      # Pinned empty (spec/model_check_spec.rb), the way `bin/fuzz`'s
+      # `KNOWN_FUZZ_FINDINGS` is: a finding a domain means to keep belongs
+      # in that domain's own declaration.
       ALLOWED_FINDINGS = {
-        "banking" => [
-          [:unacknowledged_relationship, "NotifyOnClosure"],
-          [:unknown_target_domain, "NotifyOnClosure"],
-          [: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
@@ -72,16 +105,20 @@ module Hecks
       # `hecksagon:`/`known_domains:` — both optional, both `nil`-safe
       # (every existing caller with no sibling hecksagon, or checking one
       # domain in isolation, behaves exactly as before). `hecksagon` is
-      # THIS bluebook's own sibling wiring file, if the caller loaded one
+      # this bluebook's own sibling wiring file, if the caller loaded one
       # (see `emitted_events`'s own comment on why a caller that didn't
       # simply finds none, correctly). `known_domains` is the caller's
-      # OWN corpus-wide view — every bluebook/hecksagon name it has
+      # own corpus-wide view — every bluebook/hecksagon name it has
       # booted anywhere, across every domain it has looked at, not just
       # this one — used only to catch a typo'd `across`/`uses_framework`
       # target; see `cross_domain_policy_findings`'s own comment for why
       # this can only ever be a corpus-scoped heuristic, never a general
       # correctness guarantee.
-      def call(bluebook, hecksagon: nil, known_domains: nil)
+      #
+      # `rust_target:`/`strict:` — both default false, both only change the
+      # severity of `rust_reserved_name` findings (see
+      # `rust_reserved_name_findings`); every other finding is unaffected.
+      def call(bluebook, hecksagon: nil, known_domains: nil, rust_target: false, strict: false)
         findings = []
         bluebook.aggregates.each do |aggregate|
           findings.concat(lifecycle_findings(aggregate, aggregate))
@@ -89,10 +126,68 @@ module Hecks
         end
         bluebook.process_managers.each { |process_manager| findings.concat(saga_findings(bluebook, process_manager)) }
         bluebook.policies.each { |policy| findings.concat(policy_findings(bluebook, policy, hecksagon, known_domains)) }
+        findings.concat(rust_reserved_name_findings(domain_name: bluebook.name,
+                                                    aggregate_names: bluebook.aggregates.map(&:hecks_name),
+                                                    rust_target: rust_target, strict: strict))
         findings
       end
 
-      # ── lifecycles (aggregate AND entity — a piece may declare one too) ──
+      # ── Rust reserved names ───────────────────────────────────────────
+      #
+      # A name that becomes a bare Rust module identifier with no `r#`
+      # escape hatch: an aggregate (`pub mod <name.downcase>;` plus its
+      # `<name.downcase>.rs` file) and a domain (`pub mod <name>;` and a
+      # Cargo `[features]` key). Field names are not checked — both
+      # generators already raw-escape those (`rust_ident_field`).
+      #
+      # The words come from the `RustReservedWord`/`CargoReservedName`
+      # vocabularies, the same tables `rust/project/naming.rb` and
+      # hecks-codegen's generated `reserved_names.rs` read. Both Rust
+      # generators refuse through this check (`Projector.
+      # reserved_name_refusal`, and its hecks-codegen port in `naming.rs`).
+      #
+      # Severity: a domain that only ever runs in Ruby is fine with an
+      # aggregate named `Match`, so this warns by default. It is an error
+      # when the caller says the domain has a Rust target (`rust_target:` —
+      # `bin/model_check` reads it off the domain's Cargo feature, the
+      # generators always pass it) or asks for strictness (`strict:`,
+      # `bin/model_check --strict`).
+      #
+      # The module-name transform is `downcase`, the one both generators
+      # apply to an aggregate name and to an attached chapter's name.
+      def rust_reserved_name_findings(domain_name: nil, aggregate_names: [], rust_target: false, strict: false)
+        severity = rust_target || strict ? :error : :warning
+        keywords = Hecks::Vocabulary.fetch("RustReservedWord")
+
+        findings = aggregate_names.filter_map do |name|
+          module_name = rust_module_name(name)
+          next unless keywords.include?(module_name)
+
+          Finding.new(kind: :rust_reserved_name, severity: severity, subject: name.to_s,
+                      message: "the aggregate's Rust module `#{module_name}` is a Rust keyword (RustReservedWord) — " \
+                               "`pub mod #{module_name};` has no raw-identifier escape; rename the aggregate")
+        end
+        findings.concat(domain_reserved_name_findings(domain_name, keywords, severity)) if domain_name
+        findings
+      end
+
+      def domain_reserved_name_findings(domain_name, keywords, severity)
+        module_name = rust_module_name(domain_name)
+        table = if keywords.include?(module_name)
+                  "a Rust keyword (RustReservedWord)"
+                elsif Hecks::Vocabulary.fetch("CargoReservedName").include?(module_name)
+                  "a reserved Cargo.toml key (CargoReservedName)"
+                end
+        return [] unless table
+
+        [Finding.new(kind: :rust_reserved_name, severity: severity, subject: domain_name.to_s,
+                     message: "the domain's Rust module and Cargo feature `#{module_name}` is #{table} — " \
+                              "rename the domain")]
+      end
+
+      def rust_module_name(name) = name.to_s.downcase
+
+      # ── lifecycles (aggregate and entity — a piece may declare one too) ──
 
       def lifecycle_findings(aggregate, declaring)
         lifecycle = declaring.lifecycle
@@ -164,7 +259,7 @@ module Hecks
         ).uniq
       end
 
-      # Least fixpoint from the default state: an UNCONSTRAINED
+      # Least fixpoint from the default state: an unconstrained
       # transition always fires, from wherever the machine is ; a
       # constrained one fires once any of its named sources is reached.
       def reachable_states(lifecycle)
@@ -188,8 +283,8 @@ module Hecks
         reached
       end
 
-      # A state with no OUTGOING declared path at all is exempt from the
-      # stuck-state WARNING for a different reason than "it fires an
+      # A state with no outgoing declared path at all is exempt from the
+      # stuck-state warning for a different reason than "it fires an
       # unconstrained transition" — the default state of a lifecycle
       # with only constrained transitions is legitimately allowed to sit
       # forever, since nothing about *entering* it via default implies
@@ -197,7 +292,7 @@ module Hecks
       # explicitly delivered somewhere.
       #
       # Scoped to `default` alone, and only when the lifecycle actually
-      # declares real transitions elsewhere: an EMPTY lifecycle (no
+      # declares real transitions elsewhere: an empty lifecycle (no
       # transitions at all) doesn't get this exemption — that's not "a
       # machine whose entry point deliberately awaits external action,"
       # it's much more likely a lifecycle nobody finished wiring, and
@@ -215,7 +310,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 = []
@@ -246,11 +346,11 @@ module Hecks
         end
       end
 
-      # ONE HANDLER'S OWN FINDINGS — deaf_handler, unknown_dispatch (one
+      # One handler's own findings — deaf_handler, unknown_dispatch (one
       # per dispatch), and unarmed_compensation (one per compensating
       # dispatch), pulled out of saga_findings' own handler loop; each
       # check reads only this handler plus the domain-wide emitted/verbs
-      # sets saga_findings already resolved once, no state shared BETWEEN
+      # sets saga_findings already resolved once, no state shared between
       # handlers.
       def handler_findings(bluebook, process_manager, emitted, verbs, handler)
         findings = []
@@ -266,16 +366,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,
@@ -284,7 +406,7 @@ module Hecks
                                            "checker's scope, same as CommandRules#resolve_references")
         end
 
-        # A `compensates` DECLARED WITH NOWHERE TO EVER FIRE — the exact
+        # A `compensates` declared with nowhere to ever fire — the exact
         # shape of the real bug this whole feature closes ("the
         # reversal was written and never armed"), caught at build/
         # model-check time instead of discovered in production. No
@@ -313,7 +435,7 @@ module Hecks
       end
 
       # A handler edge is only usable in the closure if it can actually
-      # FIRE — REFUSED always can (it is a compensation trigger, not an
+      # fire — REFUSED always can (it is a compensation trigger, not an
       # event), and any other handler needs its event genuinely emitted.
       # Without this, a deaf handler's declared from_state -> to_state
       # pair reads as connected even though nothing can ever traverse
@@ -347,8 +469,8 @@ module Hecks
         emitted = emitted_events(bluebook)
         findings = []
 
-        # `policy.event_name` (Naming.unqualified) — NOT `bare`, which only
-        # strips a "::" domain qualifier. An AGGREGATE-scoped policy's
+        # `policy.event_name` (Naming.unqualified) — not `bare`, which only
+        # strips a "::" domain qualifier. An aggregate-scoped policy's
         # `on_event` carries a "." aggregate qualifier instead (PolicyBuilder
         # stores whatever was typed, verbatim — see `on "Account.
         # AccountFrozen"`), and `bare` left it untouched, silently comparing
@@ -366,9 +488,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")
@@ -379,17 +519,17 @@ module Hecks
 
       # ── cross-domain policies (Context Mapping) ───────────────────────
       #
-      # `uses_framework "X"` already IS a Shared Kernel relationship — it
-      # merges X's own bluebook into THIS registry, no boundary. A cross-
-      # domain `policy ... across: "X"` already IS a Customer/Supplier
+      # `uses_framework "X"` already is a Shared Kernel relationship — it
+      # merges X's own bluebook into this registry, no boundary. A cross-
+      # domain `policy ... across: "X"` already is a Customer/Supplier
       # relationship — it dispatches into X over real cross-Lambda RPC in
       # the Rust host (`rust/host/src/lambda_client.rs`). Neither is a new
-      # word; this makes the CHOICE between them checked instead of a
+      # word; this makes the choice between them checked instead of a
       # prose comment nobody enforces (`examples/banking/bluebook/
       # banking.hecksagon`'s own hand-written note explaining why
       # Compliance is reached via `across`, never `uses_framework`).
       #
-      # NO NEW KEYWORD ANYWHERE — ADR 0025 principle 1 ("one idea, one
+      # No new keyword anywhere — ADR 0025 principle 1 ("one idea, one
       # spelling") refuses a `relationship:`/`as:` argument that would
       # just restate, as a string, the fact the chosen keyword (
       # `uses_framework` vs `across`) already states completely. The
@@ -397,14 +537,15 @@ module Hecks
       # the finding's own name and this comment, and in prose docs — not
       # in the grammar.
       def cross_domain_policy_findings(policy, hecksagon, known_domains)
+        return expected_undelivered_findings(policy, hecksagon, known_domains) if policy.expect_undelivered
         return [] unless hecksagon # no sibling hecksagon loaded — nothing to check a relationship against.
 
         target = policy.target_domain
         findings = []
 
         if hecksagon.framework_members.include?(target)
-          # SHARED KERNEL AND CUSTOMER/SUPPLIER ARE MUTUALLY EXCLUSIVE
-          # CLAIMS about the SAME target — `uses_framework` means "X is
+          # Shared kernel and customer/supplier are mutually exclusive
+          # claims about the same target — `uses_framework` means "X is
           # loaded in-process, right here"; `across` means "X is a
           # separate deployment, reached only by RPC." Declaring both is
           # either a pointless RPC to a domain already local, or a
@@ -416,7 +557,7 @@ module Hecks
                                            "relationship declarations contradict each other for the same " \
                                            "target domain")
         elsif hecksagon.subscriptions.none? { |subscribed| Naming.qualifier(subscribed) == target }
-          # THIS IS WHAT FINALLY GIVES `subscribe` REAL TEETH — checked
+          # This is what finally gives `subscribe` real teeth — checked
           # here, at model-check time, still never routed at runtime
           # (nothing dispatches off a `subscribe` line; see hecksagon.md's
           # own "checked, not routed" section). ADR 0025 names `subscribe`
@@ -429,50 +570,97 @@ module Hecks
                                            "attach it in-process instead")
         end
 
-        # TYPO DETECTION, DELIBERATELY WEAKER — `known_domains` can only
-        # ever be a MONOREPO-SCOPED heuristic: a real external hecks
+        # **Typo detection, deliberately weaker** — `known_domains` can only
+        # ever be a monorepo-scoped heuristic: a real external hecks
         # consumer's own domain (this repo's own embryonaut/lifeadelics-
         # shaped case) lives in a genuinely separate repository this
         # corpus scan can never see, so a target this check cannot find
-        # is "unknown to THIS corpus," never proof of a typo. Two real,
-        # legitimate reasons a target is unresolvable — genuinely
-        # undefined by design (the corpus's own "Notifications," used
+        # is "unknown to THIS corpus," never proof of a typo. A target
+        # undefined by design (the corpus's own "Notifications", used
         # deliberately to exercise the undelivered-reaction runtime path)
-        # and real-but-external (a separate repository) — both go in
-        # `ALLOWED_FINDINGS`, the same judged-exception mechanism this
-        # file already uses for ExternalSettlement, rather than a new
-        # keyword invented to declare "this one's fine."
+        # declares so on its own policy — `expect_undelivered: true`,
+        # checked by `expected_undelivered_findings` — rather than being
+        # named in a core allowlist.
         if known_domains && !known_domains.include?(target)
           findings << Finding.new(kind: :unknown_target_domain, severity: :error, subject: policy.name,
                                   message: "across #{target.inspect} names a domain nowhere in the corpus " \
-                                           "this check has booted — a typo, or a real domain intentionally " \
-                                           "outside this corpus (undefined by design, or living in a " \
-                                           "separate repository) belongs in ALLOWED_FINDINGS, named and " \
-                                           "explained, not silently assumed correct")
+                                           "this check has booted — a typo, or a target intentionally never " \
+                                           "reached, which the policy itself declares with " \
+                                           "across #{target.inspect}, expect_undelivered: true")
         end
 
         findings
       end
 
+      # A declared undelivered target, held to its declaration. The two
+      # findings an unreachable `across` target raises (unknown target,
+      # unacknowledged relationship) are what the policy declared it
+      # expects, so they are not raised. What is raised is the declaration
+      # going stale: the target is a domain this corpus actually booted,
+      # or the sibling hecksagon attaches or subscribes to it — either way
+      # the reaction can be delivered, and the declaration is now a lie.
+      # `known_domains` is nil for a single-target run, which can then only
+      # check the hecksagon half.
+      def expected_undelivered_findings(policy, hecksagon, known_domains)
+        target  = policy.target_domain
+        reached = []
+        reached << "#{target} is a domain this corpus boots" if known_domains&.include?(target)
+        if hecksagon
+          reached << "this hecksagon uses_framework #{target.inspect}" if hecksagon.framework_members.include?(target)
+          if hecksagon.subscriptions.any? { |subscribed| Naming.qualifier(subscribed) == target }
+            reached << "this hecksagon subscribes to #{target}"
+          end
+        end
+        return [] if reached.empty?
+
+        [Finding.new(kind: :stale_undelivered_expectation, severity: :error, subject: policy.name,
+                     message: "across #{target.inspect}, expect_undelivered: true — but #{reached.join(' and ')}, " \
+                              "so the reaction can be delivered after all; drop expect_undelivered: or remove " \
+                              "what reaches #{target}")]
+      end
+
       # ── shared enumeration ────────────────────────────────────────────
 
-      # A PORT OPERATION EMITS TOO — the primary/driving port an adapter
+      # A port operation emits too — the primary/driving port an adapter
       # outside the bluebook calls through (see hecksagon_builder.rb) is a
       # second, real source of events, alongside a command's own `emits`.
-      # Ports attach to the aggregate/bluebook from the SIBLING `.hecksagon`
+      # Ports attach to the aggregate/bluebook from the sibling `.hecksagon`
       # file, not this one — a caller that boots only the `.bluebook` (as
       # 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 +678,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