hecks 1.3.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,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
+      # 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:
+        # 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
@@ -82,7 +81,7 @@ module Hecks
         # 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,
+        # 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
@@ -92,7 +91,7 @@ module Hecks
         # 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
+        # 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
@@ -106,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))
@@ -123,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
@@ -198,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)
@@ -222,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
@@ -231,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
@@ -249,7 +310,7 @@ module Hecks
 
       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.
@@ -285,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 = []
@@ -305,7 +366,7 @@ module Hecks
         end
 
         handler.dispatches.each do |dispatch|
-          # ALWAYS THIS DOMAIN — same fix, same reason, as `SagaInterpreter
+          # **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
@@ -320,7 +381,7 @@ module Hecks
           # — 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,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
@@ -374,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
@@ -408,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
@@ -429,13 +490,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,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
@@ -476,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
@@ -495,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`
@@ -508,43 +570,67 @@ 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
+      # 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,7 +638,7 @@ 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.
       def emitted_events(bluebook)
@@ -566,7 +652,7 @@ 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`
@@ -592,13 +678,13 @@ 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.
       def port_verbs_of(bluebook)
@@ -611,7 +697,7 @@ 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

data/lib/hecks/bluebook/pattern_subset.rb

@@ -1,24 +1,24 @@
 module Hecks
   module Bluebook
-    # WHICH REGEXES A BLUEBOOK MAY SAY.
+    # **Which regexes a bluebook may say**.
     #
     # A `pattern:` is a fact about a value, carried in a bluebook — declared
     # data, not Ruby code, so it must not lean on what any one engine happens
     # to accept. Regex engines disagree in two different ways :
     #
-    #   ONLY A BACKTRACKING ENGINE CAN MATCH IT — lookahead, lookbehind,
+    #   only a backtracking engine can match it — lookahead, lookbehind,
     #   backreferences, atomic groups, possessive quantifiers. None of these
     #   can be matched in linear time, and linear-time engines refuse them
     #   outright. Refused here for the same reason.
     #
-    #   EVERY ENGINE PARSES IT AND THEY MEAN DIFFERENT THINGS — the dangerous
+    #   every engine parses it and they mean different things — the dangerous
     #   half, because nothing errors. `\d` `\w` `\s` are ASCII in some engines
     #   and Unicode in others ; `[:digit:]` and friends flip the same way in
     #   the other direction. Both families are refused, and a domain spells
     #   the range it means.
     #
     # What remains — explicit ranges, alternation, quantifiers, anchors,
-    # groups — reads identically everywhere, with `^` and `$` as LINE anchors
+    # groups — reads identically everywhere, with `^` and `$` as line anchors
     # (Ruby's reading). The evidence is spec/corpus/fixtures/patterns.json.
     module PatternSubset
       Rejection = Struct.new(:construct, :reason)
@@ -57,13 +57,13 @@ module Hecks
 
       # nil when the pattern is admitted, a Rejection when it is not.
       #
-      # A CHARACTER WALK, deliberately plain : the subset is defined by this
+      # A character walk, deliberately plain : the subset is defined by this
       # walk, and a cleverer spelling would hide what it admits. An escaped
-      # construct is a LITERAL, not a violation — `\(\?=` is the three
+      # construct is a literal, not a violation — `\(\?=` is the three
       # characters "(?=" and says nothing about lookahead — which is why this
       # steps over each backslash pair rather than matching the pattern as a
       # whole.
-      # One character walk is the subset's DEFINITION (see the method
+      # One character walk is the subset's definition (see the method
       # comment above): each construct-check is a branch in a single
       # ordered pass sharing `index`/`in_class`/`class_start`. Splitting
       # the branches into separate methods would force those three cursor
@@ -75,7 +75,7 @@ module Hecks
       def validate(pattern)
         chars = pattern.to_s.chars
         index = 0
-        # A CHARACTER-CLASS INTERIOR IS A DIFFERENT ALPHABET : inside `[...]`,
+        # A character-class interior is a different alphabet : inside `[...]`,
         # `*`, `+`, `?`, `(`, `?` are literal characters, not quantifiers or
         # group syntax — `[*+]` means "a literal asterisk or plus". `]` is
         # only the class's close when it isn't the first character after `[`
@@ -132,7 +132,7 @@ module Hecks
         nil
       end
 
-      # SPELLED OUT, not derived from the key : these strings are the refusal
+      # Spelled out, not derived from the key : these strings are the refusal
       # a caller reads.
       CONSTRUCTS = {
         backreference:       "backreference",

data/lib/hecks/bluebook/policy.rb

@@ -1,5 +1,5 @@
-# GENERATED — projected from the language's own Policy aggregate.
-# DO NOT EDIT: the holding half is rendered, and Behaviour::Policy
+# Generated — projected from the language's own Policy aggregate.
+# Do not edit: the holding half is rendered, and Behaviour::Policy
 # is where anything hand-written belongs.
 require_relative "behaviour/policy"
 
@@ -10,28 +10,30 @@ module Hecks
       include Behaviour::Policy
 
       emits_ir(
-        name:            :name,
-        on_event:        :on_event,
-        trigger_command: :trigger_command,
-        target_domain:   :target_domain,
-        where:           :where,
-        for_each:        :for_each,
-        with_spec:       -> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } },
-        where_ast:       -> { where_ast }
+        name:               :name,
+        on_event:           :on_event,
+        trigger_command:    :trigger_command,
+        target_domain:      :target_domain,
+        expect_undelivered: :expect_undelivered,
+        where:              :where,
+        for_each:           :for_each,
+        with_spec:          -> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } },
+        where_ast:          -> { where_ast }
       )
 
-      attr_reader :name, :on_event, :trigger_command, :target_domain, :where, :for_each, :with_spec
+      attr_reader :name, :on_event, :trigger_command, :target_domain, :expect_undelivered, :where, :for_each, :with_spec
 
-      # AGGREGATE, DECLARED AND DELIBERATELY OFF THE WIRE
+      # Aggregate, declared and deliberately off the wire
       # the wire format is a pinned contract, and it does not carry
       # where a policy was written before the builder hoisted it
       attr_accessor :aggregate
 
-      def initialize(name:, on_event: nil, trigger_command: nil, target_domain: nil, where: nil, for_each: nil, with_spec: [], aggregate: nil)
+      def initialize(name:, on_event: nil, trigger_command: nil, target_domain: nil, expect_undelivered: false, where: nil, for_each: nil, with_spec: [], aggregate: nil)
         @name = name.to_s
         @on_event = on_event
         @trigger_command = trigger_command
         @target_domain = target_domain
+        @expect_undelivered = expect_undelivered.to_s == "true"
         @where = where
         @for_each = for_each
         @with_spec = with_spec