hecks 1.3.0 → 1.5.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,45 +31,42 @@ 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
-      # `state "x"` line never named by any handler's own from:/to:, a
-      # pure declaration-drift artifact. States are DERIVED from the
+      # S7, ADR 0025 — an ExternalSettlement finding once lived here as an
+      # allowlist entry and is gone now, 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
       # 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
+      # longer exists to be unreachable — the finding that entry 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:
+        # QualityControl was the first domain in this corpus to trigger an
+        # `asks`/`tells` port operation from a `policy`, and once carried
+        # 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
@@ -80,19 +79,19 @@ module Hecks
         #
         # `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,
+        # tracing the real dispatch path rather than trusting a stale
+        # comment that once sat 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
+        # dot-joined tail correctly (the same fix `ReactionInvocation#
+        # resolve_target` already carries) — 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
+        # 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
@@ -103,31 +102,156 @@ module Hecks
 
       module_function
 
+      # Runs every static model check over `bluebook` and returns what it
+      # finds.
+      #
       # `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.
+      #
+      # @param bluebook [Bluebook::Chapter] the assembled chapter to check
+      # @param hecksagon [Bluebook::Hecksagon, nil] this bluebook's own
+      #   sibling wiring file, if the caller loaded one
+      # @param known_domains [Set<String>, nil] every bluebook/hecksagon
+      #   name the caller has booted anywhere in this corpus scan
+      # @param global_emitted_events [Set<String>, nil] every bare event
+      #   name any domain the caller has booted this run emits — lets a
+      #   same-domain-target policy (e.g. one built by `translates`)
+      #   reacting to a genuinely foreign event avoid a false `deaf_policy`
+      #   finding; `nil` (every pre-existing call site) keeps today's
+      #   single-domain-only check
+      # @param rust_target [Boolean] whether this domain has a real Rust
+      #   target, raising `rust_reserved_name` findings to error
+      # @param strict [Boolean] whether to raise every `rust_reserved_name`
+      #   finding to error regardless of `rust_target`
+      # @return [Array<Finding>] every finding this bluebook triggers,
+      #   across its lifecycles, sagas, policies, and Rust-reserved names
+      def call(bluebook, hecksagon: nil, known_domains: nil, global_emitted_events: nil, rust_target: false, strict: false)
         findings = []
         bluebook.aggregates.each do |aggregate|
           findings.concat(lifecycle_findings(aggregate, aggregate))
           aggregate.entities.each { |entity| findings.concat(lifecycle_findings(aggregate, entity)) }
         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)) }
+        bluebook.policies.each do |policy|
+          findings.concat(policy_findings(bluebook, policy, hecksagon, known_domains, global_emitted_events))
+        end
+        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
+
+      # ── 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.
+      #
+      # @param domain_name [String, Symbol, nil] the domain's own name, or
+      #   `nil` to skip the domain-level check
+      # @param aggregate_names [Array<String, Symbol>] every aggregate name
+      #   to check
+      # @param rust_target [Boolean] whether this domain has a real Rust
+      #   target, raising severity to error
+      # @param strict [Boolean] whether to raise severity to error
+      #   regardless of `rust_target`
+      # @return [Array<Finding>] one `:rust_reserved_name` finding per
+      #   aggregate or domain name that collides with a Rust or Cargo
+      #   reserved word
+      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
 
-      # ── lifecycles (aggregate AND entity — a piece may declare one too) ──
+      # Checks the domain's own module/Cargo-feature name, one level up
+      # from `rust_reserved_name_findings`'s own per-aggregate check.
+      #
+      # @param domain_name [String, Symbol] the domain's own name
+      # @param keywords [Array<String>] the admitted `RustReservedWord`
+      #   vocabulary rows
+      # @param severity [Symbol] the finding severity to use, `:error` or
+      #   `:warning`
+      # @return [Array<Finding>] a single-element array holding a
+      #   `:rust_reserved_name` finding, or `[]` if `domain_name` collides
+      #   with no reserved word or Cargo key
+      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
+
+      # Derives the Rust module identifier both generators derive from a
+      # name.
+      #
+      # @param name [String, Symbol] an aggregate or domain name
+      # @return [String] the Rust module identifier both generators derive
+      #   from `name`
+      def rust_module_name(name) = name.to_s.downcase
+
+      # ── lifecycles (aggregate and entity — a piece may declare one too) ──
 
+      # Runs every lifecycle-shaped model check for one declaring
+      # construct's own lifecycle, if it has one.
+      #
+      # @param aggregate [Bluebook::Aggregate] the root aggregate `declaring`
+      #   belongs to
+      # @param declaring [Bluebook::Aggregate, Bluebook::Entity] the
+      #   construct whose own lifecycle to check — `aggregate` itself, or
+      #   one of its entities
+      # @return [Array<Finding>] `[]` if `declaring` has no lifecycle;
+      #   otherwise every `unknown_command`/`unreachable_state`/
+      #   `dead_transition`/`stuck_state` finding its lifecycle triggers
       def lifecycle_findings(aggregate, declaring)
         lifecycle = declaring.lifecycle
         return [] unless lifecycle
@@ -146,6 +270,15 @@ module Hecks
         findings
       end
 
+      # Finds every declared state a lifecycle's own reachability walk
+      # never reaches.
+      #
+      # @param lifecycle [Bluebook::Lifecycle] the lifecycle being checked
+      # @param full [Array<String>] every state `full_states` declares
+      # @param reached [Set<String>] every state `reachable_states` reaches
+      # @param subject [String] the finding's own subject label
+      # @return [Array<Finding>] one `:unreachable_state` finding per
+      #   declared state that `reached` does not cover
       def unreachable_state_findings(lifecycle, full, reached, subject)
         (full - reached.to_a).map do |state|
           Finding.new(kind: :unreachable_state, severity: :error, subject: subject,
@@ -154,6 +287,13 @@ module Hecks
         end
       end
 
+      # Finds every constrained transition that can never fire.
+      #
+      # @param lifecycle [Bluebook::Lifecycle] the lifecycle being checked
+      # @param reached [Set<String>] every state `reachable_states` reaches
+      # @param subject [String] the finding's own subject label
+      # @return [Array<Finding>] one `:dead_transition` finding per
+      #   constrained transition whose `from:` states are all unreached
       def dead_transition_findings(lifecycle, reached, subject)
         lifecycle.transitions.filter_map do |command, transition|
           next unless transition.constrained?
@@ -165,6 +305,14 @@ module Hecks
         end
       end
 
+      # Finds every reached state with no transition ever leaving it.
+      #
+      # @param lifecycle [Bluebook::Lifecycle] the lifecycle being checked
+      # @param reached [Set<String>] every state `reachable_states` reaches
+      # @param subject [String] the finding's own subject label
+      # @return [Array<Finding>] one `:stuck_state` finding per reached,
+      #   non-exempt state with no transition ever leaving it (skipped
+      #   entirely when any transition is unconstrained)
       def stuck_state_findings(lifecycle, reached, subject)
         any_unconstrained = lifecycle.transitions.any? { |_, t| !t.constrained? }
         (reached - terminal_exempt(lifecycle)).filter_map do |state|
@@ -177,6 +325,15 @@ module Hecks
         end
       end
 
+      # Finds every transition named after a command this construct does
+      # not declare.
+      #
+      # @param lifecycle [Bluebook::Lifecycle] the lifecycle being checked
+      # @param commands [Array<String>] every command name the declaring
+      #   construct actually declares
+      # @param subject [String] the finding's own subject label
+      # @return [Array<Finding>] one `:unknown_command` finding per
+      #   transition named after a command `commands` does not list
       def unknown_transition_commands(lifecycle, commands, subject)
         lifecycle.transitions.filter_map do |command, _transition|
           next if commands.include?(command)
@@ -190,6 +347,10 @@ module Hecks
       # from-only state (declared nowhere as a target) is real and is
       # exactly the hole `Lifecycle#states` leaves: it answers default
       # plus targets only.
+      #
+      # @param lifecycle [Bluebook::Lifecycle] the lifecycle being checked
+      # @return [Array<String>] every state `lifecycle` declares, in any
+      #   role (default, target, or from), unique
       def full_states(lifecycle)
         (
           [lifecycle.default] +
@@ -198,9 +359,13 @@ 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.
+      #
+      # @param lifecycle [Bluebook::Lifecycle] the lifecycle being checked
+      # @return [Set<String>] every state reachable from `lifecycle`'s own
+      #   default state
       def reachable_states(lifecycle)
         reached = Set.new([lifecycle.default])
         loop do
@@ -222,8 +387,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
@@ -231,13 +396,17 @@ 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
       # should still warn (see spec/fixtures/model_check/lifecycle_
       # findings.bluebook's own Widget::Part, which stays warned on
       # purpose).
+      #
+      # @param lifecycle [Bluebook::Lifecycle] the lifecycle being checked
+      # @return [Array<String>] `[lifecycle.default]` when it is exempt from
+      #   the stuck-state warning, `[]` otherwise
       def terminal_exempt(lifecycle)
         return [] if lifecycle.transitions.empty?
 
@@ -247,9 +416,18 @@ module Hecks
 
       # ── process managers / sagas ──────────────────────────────────────
 
+      # Runs every saga-shaped model check for one process manager.
+      #
+      # @param bluebook [Bluebook::Chapter] the assembled chapter
+      #   `process_manager` belongs to
+      # @param process_manager [Bluebook::ProcessManager] the process
+      #   manager to check
+      # @return [Array<Finding>] every `deaf_trigger`/`unreachable_pm_state`/
+      #   `deaf_handler`/`unknown_dispatch`/`unarmed_compensation`/
+      #   `dead_compensation` finding this process manager triggers
       def saga_findings(bluebook, process_manager)
         emitted = emitted_events(bluebook)
-        # (domain, aggregate, command) TRIPLES, not raw strings — see
+        # (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.
@@ -267,6 +445,15 @@ module Hecks
         findings
       end
 
+      # Finds every declared `starts_on`/`ends_on` event this domain never
+      # emits.
+      #
+      # @param process_manager [Bluebook::ProcessManager] the process
+      #   manager being checked
+      # @param emitted [Array<String>] every bare event name this domain
+      #   actually emits
+      # @return [Array<Finding>] one `:deaf_trigger` finding per declared
+      #   `starts_on`/`ends_on` event this domain never emits
       def deaf_trigger_findings(process_manager, emitted)
         [process_manager.starts_on, process_manager.ends_on].compact.filter_map do |event|
           next if emitted.include?(bare(event))
@@ -277,6 +464,14 @@ module Hecks
         end
       end
 
+      # Finds every declared state no handler chain ever reaches.
+      #
+      # @param process_manager [Bluebook::ProcessManager] the process
+      #   manager being checked
+      # @param reached [Set<String>] every state `pm_reachable_states`
+      #   reaches
+      # @return [Array<Finding>] one `:unreachable_pm_state` finding per
+      #   declared state that `reached` does not cover
       def unreachable_pm_state_findings(process_manager, reached)
         (Array(process_manager.states) - reached.to_a).map do |state|
           Finding.new(kind: :unreachable_pm_state, severity: :error, subject: process_manager.name,
@@ -285,17 +480,31 @@ 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.
+      #
+      # @param bluebook [Bluebook::Chapter] the assembled chapter
+      #   `process_manager` belongs to
+      # @param process_manager [Bluebook::ProcessManager] the process
+      #   manager `handler` belongs to
+      # @param emitted [Array<String>] every bare event name this domain
+      #   actually emits
+      # @param verbs [Array<Array(String, String, String)>] every command
+      #   this domain declares, parsed as `Naming.split_verb`
+      #   `[domain, aggregate, command]` triples
+      # @param handler [Bluebook::ProcessManagerHandler] the handler to
+      #   check
+      # @return [Array<Finding>] every `deaf_handler`/`unknown_dispatch`/
+      #   `unarmed_compensation` finding this handler triggers
       def handler_findings(bluebook, process_manager, emitted, verbs, handler)
         findings = []
 
-        # The compensating leg answers REFUSED, a synthetic trigger no
-        # command ever emits by name (ProcessManager::REFUSED) — not
+        # The compensating leg answers `REFUSED`, a synthetic trigger no
+        # command ever emits by name (`ProcessManager::REFUSED`) — not
         # a deaf handler, the one handler this domain's own events can
         # never satisfy on purpose.
         if handler.event_type != ProcessManager::REFUSED && !emitted.include?(bare(handler.event_type))
@@ -305,22 +514,22 @@ module Hecks
         end
 
         handler.dispatches.each do |dispatch|
-          # 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
+          # **Always this domain** — same fix, same reason, as `SagaInterpreter
+          # #qualified` (BUG#6). Guessing instead — reading a dispatch whose
+          # own `command_name` still carries a leftover `::` after `Naming.
+          # command_ref`'s own rewrite as "already qualified" and leaving it
+          # alone — would hit 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
+          # so this checker 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
+          # 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
@@ -345,11 +554,11 @@ 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
-        # handler anywhere answers REFUSED (`process_manager.saga?` false) means
+        # handler anywhere answers `REFUSED` (`process_manager.saga?` false) means
         # `SagaInterpreter#unwind` never runs for this process
         # manager at all, so a declared `compensates` is structurally
         # unreachable — not a warning about style, a dead declaration.
@@ -365,6 +574,16 @@ module Hecks
         findings
       end
 
+      # Checks whether a saga's own compensation leaves an unreachable
+      # state.
+      #
+      # @param process_manager [Bluebook::ProcessManager] the process
+      #   manager being checked
+      # @param reached [Set<String>] every state `pm_reachable_states`
+      #   reaches
+      # @return [Array<Finding>] a single-element array holding a
+      #   `:dead_compensation` finding, or `[]` if `process_manager` has no
+      #   saga or its own compensation leaves a reached state
       def dead_compensation_findings(process_manager, reached)
         return [] unless process_manager.saga? && !reached.include?(process_manager.saga.from_state)
 
@@ -374,13 +593,21 @@ 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
       # it, which would hide exactly the states this walk exists to
       # catch (a state only "reachable" through a handler that itself
       # never fires).
+      #
+      # @param process_manager [Bluebook::ProcessManager] the process
+      #   manager being checked
+      # @param emitted [Array<String>] every bare event name this domain
+      #   actually emits
+      # @return [Set<String>] every state reachable from
+      #   `process_manager`'s own first declared state, through handlers
+      #   that can actually fire
       def pm_reachable_states(process_manager, emitted)
         return Set.new if Array(process_manager.states).empty?
 
@@ -402,14 +629,28 @@ module Hecks
 
       # ── policies ───────────────────────────────────────────────────────
 
-      def policy_findings(bluebook, policy, hecksagon, known_domains)
+      # Runs every same-domain policy check, or defers to
+      # `cross_domain_policy_findings` for a policy that targets another
+      # domain.
+      #
+      # @param bluebook [Bluebook::Chapter] the assembled chapter `policy`
+      #   belongs to
+      # @param policy [Bluebook::Policy] the policy to check
+      # @param hecksagon [Bluebook::Hecksagon, nil] this bluebook's own
+      #   sibling wiring file, if the caller loaded one
+      # @param known_domains [Set<String>, nil] every bluebook/hecksagon
+      #   name the caller has booted anywhere in this corpus scan
+      # @return [Array<Finding>] every `deaf_policy`/`unknown_trigger`
+      #   finding this policy triggers, or `cross_domain_policy_findings`'s
+      #   own return for a cross-domain policy
+      def policy_findings(bluebook, policy, hecksagon, known_domains, global_emitted_events = nil)
         return cross_domain_policy_findings(policy, hecksagon, known_domains) if policy.target_domain
 
         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
@@ -419,7 +660,18 @@ module Hecks
         # prior aggregate-scoped policy (ReviewOnFreeze) is also cross-domain
         # (`across "Compliance"`), which exits this method one line above
         # before the mismatch is ever reached.
-        unless emitted.include?(policy.event_name)
+        # `global_emitted_events` — a `translates` (hecksagon-level)
+        # reaction is BUILT as the exact same same-domain-target `Policy`
+        # an ordinary `policy` block is (no `target_domain`, so it never
+        # reaches `cross_domain_policy_findings` above), but its whole
+        # point is to react to a FOREIGN domain's own event — this
+        # domain's own `emitted_events(bluebook)` was never going to
+        # contain it. Checked only as a FALLBACK, after the local check
+        # already failed, so a real same-domain typo still gets flagged
+        # exactly as before whenever the caller has no cross-domain set
+        # to offer (nil — every existing call site, unchanged) or the
+        # event genuinely isn't emitted anywhere this run examined.
+        unless emitted.include?(policy.event_name) || global_emitted_events&.include?(policy.event_name)
           findings << Finding.new(kind: :deaf_policy, severity: :error, subject: policy.name,
                                   message: "on #{policy.on_event.inspect}, which no command in this domain emits")
         end
@@ -429,13 +681,13 @@ module Hecks
         # "#{domain}::#{trigger_command}" — the same join `verbs_of` builds
         # independently, so the two spellings have to be compared as FQNs.
         #
-        # COMPARED AS A TRIPLE, NOT A STRING — `handler_findings`'s own
+        # 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::
+        # 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 —
+        # 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
@@ -458,32 +710,44 @@ 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
       # DDD vocabulary (Shared Kernel, Customer/Supplier) lives here, in
       # the finding's own name and this comment, and in prose docs — not
       # in the grammar.
+      #
+      # @param policy [Bluebook::Policy] the cross-domain policy to check
+      # @param hecksagon [Bluebook::Hecksagon, nil] this bluebook's own
+      #   sibling wiring file, if the caller loaded one
+      # @param known_domains [Set<String>, nil] every bluebook/hecksagon
+      #   name the caller has booted anywhere in this corpus scan
+      # @return [Array<Finding>] `expected_undelivered_findings`'s own
+      #   return for a policy declared `expect_undelivered`; otherwise every
+      #   `contradictory_relationship`/`unacknowledged_relationship`/
+      #   `unknown_target_domain` finding this policy triggers
       def cross_domain_policy_findings(policy, hecksagon, known_domains)
-        return [] unless hecksagon # no sibling hecksagon loaded — nothing to check a relationship against.
+        return expected_undelivered_findings(policy, hecksagon, known_domains) if policy.expect_undelivered
+        # No sibling hecksagon loaded — nothing to check a relationship against.
+        return [] unless hecksagon
 
         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
@@ -495,7 +759,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`
@@ -508,43 +772,77 @@ 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.
+      #
+      # @param policy [Bluebook::Policy] the `expect_undelivered` policy to
+      #   check
+      # @param hecksagon [Bluebook::Hecksagon, nil] this bluebook's own
+      #   sibling wiring file, if the caller loaded one
+      # @param known_domains [Set<String>, nil] every bluebook/hecksagon
+      #   name the caller has booted anywhere in this corpus scan
+      # @return [Array<Finding>] a single-element array holding a
+      #   `:stale_undelivered_expectation` finding, or `[]` if the target
+      #   remains genuinely unreachable
+      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
+      # 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
@@ -552,9 +850,14 @@ module Hecks
       # 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`/
+      # 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.
+      #
+      # @param bluebook [Bluebook::Chapter] the assembled chapter to
+      #   enumerate
+      # @return [Array<String>] every bare event name this domain's
+      #   commands and port operations emit, answer, or refuse, unique
       def emitted_events(bluebook)
         aggregate_emits = bluebook.aggregates.flat_map do |aggregate|
           aggregate.commands.map(&:emits) +
@@ -566,13 +869,18 @@ module Hecks
         (aggregate_emits + chapter_emits).flatten.compact.uniq
       end
 
-      # ONE OPERATION, EITHER OF ITS OWN SOURCES OF EVENTS — an inbound
+      # 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.
+      #
+      # @param ports [Array<Bluebook::DomainPort>] the ports to enumerate
+      # @return [Array<String, nil>] every event name each operation emits,
+      #   answers, or refuses; `nil` entries included (compacted by the
+      #   caller)
       def port_operation_events(ports)
         ports.flat_map { |port| port.operations.flat_map { |op| [*op.emits, op.answers, op.refuses] } }
       end
@@ -581,6 +889,12 @@ module Hecks
       # carries and fuzzing/sequence_generator/catalog.rb builds
       # independently for the same reason: a saga dispatch and a fuzzer
       # step both have to name a verb the same way the door does.
+      #
+      # @param bluebook [Bluebook::Chapter] the assembled chapter to
+      #   enumerate
+      # @return [Array<String>] every command's own fully-qualified verb,
+      #   `"Domain::Aggregate.Command"` or
+      #   `"Domain::Aggregate.Entity.Command"`
       def verbs_of(bluebook)
         bluebook.aggregates.flat_map do |aggregate|
           verbs = aggregate.commands.map { |command| "#{bluebook.name}::#{aggregate.hecks_name}.#{command.hecks_name}" }
@@ -592,15 +906,20 @@ module Hecks
         end
       end
 
-      # AN AGGREGATE-OWNED PORT OPERATION IS A TRIGGERABLE VERB TOO —
+      # 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
+      # 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.
+      #
+      # @param bluebook [Bluebook::Chapter] the assembled chapter to
+      #   enumerate
+      # @return [Array<String>] every aggregate-owned port operation's own
+      #   fully-qualified verb, `"Domain::Aggregate.Port.Operation"`
       def port_verbs_of(bluebook)
         bluebook.aggregates.flat_map do |aggregate|
           aggregate.ports.flat_map do |port|
@@ -611,16 +930,27 @@ module Hecks
         end
       end
 
-      # EVERY TRIGGERABLE VERB, AS A TRIPLE — `verbs_of` (ordinary/entity
+      # 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).
+      #
+      # @param bluebook [Bluebook::Chapter] the assembled chapter to
+      #   enumerate
+      # @return [Set<Array(String, String, String)>] every triggerable
+      #   verb, parsed as `Naming.split_verb` `[domain, aggregate,
+      #   command]` triples
       def triggerable_verbs(bluebook)
         (verbs_of(bluebook) + port_verbs_of(bluebook)).to_set { |verb| Naming.split_verb(verb) }
       end
 
+      # Strips a domain qualifier off an event name.
+      #
+      # @param event [String, Symbol] an event name, qualified
+      #   (`"Domain::Event"`) or bare
+      # @return [String] `event`'s own bare name, past the last `::`
       def bare(event) = event.to_s.split("::").last
     end
   end