hecks 0.3.0 → 1.0.1

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

@@ -53,6 +53,14 @@ module Hecks
         # argument became indistinguishable from one carrying a literal string.
         def with_spec_rows(node) = pair_rows(node.to_h[:with_spec])
 
+        # THE SAME READ, ONE LEVEL IN — `compensates` folds `DispatchSpec`
+        # into the language's own `compensates_command_name`/
+        # `compensates_with_spec` (`Assembly::Contracts`' own comment on
+        # "Dispatch"), so its OWN with_spec pairs live nested one hash
+        # down from where `with_spec_rows` looks. `&.dig(...)` — no
+        # compensation at all is not an error, it is `pair_rows(nil)`, empty.
+        def compensates_with_spec_rows(node) = pair_rows(node.to_h[:compensates]&.dig(:with_spec))
+
         # A read model carries the same options an ask does, plus its filters — see
         # option_rows.
         def read_model_option_rows(node) = option_rows(node, filters: true)
@@ -155,10 +163,12 @@ module Hecks
         # was being handed a blank and could never refuse.
         def mutation_rows(node)
           Array(node.mutations).flat_map do |mutation|
-            # `:delegate` (CommandBuilder#delegates_to's own comment) rides
-            # the SAME multi-binding shape `:append` does — `with: {...}`
-            # is a field map, same as append's own `fields:`.
-            next set_row(mutation) unless [:append, :delegate].include?(mutation.op)
+            # `:delegate`/`:corrects` (CommandBuilder#delegates_to's and
+            # #corrects_impl's own comments) ride the SAME multi-binding
+            # shape `:append` does — `with: {...}`/the assembled
+            # `as:`/`reason:`/`reverses:` hash is a field map, same as
+            # append's own `fields:`.
+            next set_row(mutation) unless [:append, :delegate, :corrects].include?(mutation.op)
 
             mutation.source.map do |field, argument|
               # Spelled the way Mutation#appended_fields spells it, because

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

@@ -207,9 +207,22 @@ module Hecks
         # at a time.
         def members_row(row) = members_of(row)
 
+        # THE KEY IS STRINGIFIED, NEVER THE VALUE — the same split
+        # `Bluebook::ValueObject#to_h`'s own `members:` emission makes
+        # (lib/hecks/bluebook/value_object.rb, L7 docs/audits/
+        # 2026-08-11-bug-triage.md). `Pair.value` is declared `String`
+        # (shape.bluebook), but a real pair can hold whatever native Ruby
+        # type the source member line actually wrote (`StatementFrequency`'s
+        # own `retention_months: 84`, examples/banking/bluebook/
+        # statements.bluebook) — `text` already unwraps the stored Value to
+        # that real type, so calling `.to_s` here erased it a second time,
+        # on the side spec/round_trip_spec.rb compares straight against a
+        # fresh raw load (`Reconstruction.of` directly, no Assembly in
+        # between): `declared 84, read back "84"` the moment `to_h` stopped
+        # erasing it on the OTHER side and this one kept erasing it alone.
         def members_of(value_object_row)
           Array(value_object_row[:members]).map do |member|
-            Array(member[:pairs]).map { |pair| [text(pair[:key]).to_s, text(pair[:value]).to_s] }
+            Array(member[:pairs]).map { |pair| [text(pair[:key]).to_s, text(pair[:value])] }
           end
         end
 
@@ -238,7 +251,12 @@ module Hecks
             # Symbol there — the IR was not uniform about it, and only a round trip
             # ever said so.
             identified_by: identity_paths(row),
-            attributes:    Array(row[:attributes]).map { |field| shape_field(field) },
+            # `text(row[:aggregate])` — the OWNING aggregate, the same one
+            # `Judge#owning_aggregate_ref` resolved this piece's own
+            # attribute types against on the way in, so reconstruction reads
+            # a value-object-typed attribute back the identical way an
+            # aggregate's own is (`Shapes#shape_field`'s own comment).
+            attributes:    Array(row[:attributes]).map { |field| shape_field(field, text(row[:aggregate])) },
             # ADR 0028 — the SAME shape `aggregate(row)`'s own
             # `preconditions:` reads two hand-typed methods up, read by
             # hand for the identical reason: `entity(row)` is hand-typed
@@ -301,7 +319,28 @@ module Hecks
                       dispatches: Array(row[:dispatches]).map { |leg| dispatch(leg) })
         end
 
-        def dispatch(row) = declaration("Dispatch", row)
+        # `compensates` — TWO FLAT FIELDS on this same row
+        # (`process_manager.bluebook`'s own comment on `Dispatch` for
+        # why), assembled BY HAND into the shape its own field actually
+        # is — `declaration()`'s generic per-field hash-build has no
+        # way to turn two cells into a second object, so this reads
+        # them directly and passes the result through `extra:`, the
+        # same seam `handler`/`process_manager` already use for a
+        # `:children` shape a flat Contract cannot describe.
+        # `compensates_command_name` absent means no compensation at
+        # all — a plain dispatch with nothing to undo. A PLAIN HASH, the
+        # SAME declaration shape `to_h` spells for everything else in
+        # this file (this file's own top comment) — never a real
+        # `DispatchSpec` here; `Assembly#dispatch` is the one place a
+        # declaration hash becomes the real object, and building it
+        # twice, in two different shapes, is exactly the kind of drift
+        # this whole arc exists to remove.
+        def dispatch(row)
+          name = text(row[:compensates_command_name])
+          compensates = name && { command_name: name, with_spec: pairs(row[:compensates_with_spec]) }
+
+          declaration("Dispatch", row, compensates: compensates)
+        end
 
         def read_model(row)
           declaration("ReadModel", row).merge(query_name: text(row[:query_name])).merge(options_of(row))

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

@@ -52,14 +52,33 @@ module Hecks
         def identity_path(part) = text(part[:value]).to_s
 
         # An argument, a parameter, a piece's attribute — the three places an
-        # attribute is written that carry no owner id to strip.
+        # attribute is written that carry no owner id to strip... except a
+        # piece's own attribute now does : an entity is its own root (repeating
+        # the aggregate's whole shape one level down), so ITS attributes name a
+        # value object exactly the way an aggregate's own do (`Judge#cell`'s own
+        # comment), and reconstruction has to undo the same owned-vs-reference
+        # split `attribute`, below, already undoes for an aggregate — not the
+        # cruder "any qualified name is a Reference" guess this used before,
+        # which mistook a piece's own value-object type for a cross-aggregate
+        # head every time.
         #
-        # A REFERENCE among them came in as the head's ID, because that is what
-        # Command/Entity/Query.Reference offer, so it goes back out as the
-        # encoding the IR spells. A qualified name is the tell : an ordinary
-        # type names something declared beside it (`Money`, `AccountNumber`) and
-        # never carries a chapter, while a head's id always does.
-        def shape_field(field)
+        # `aggregate_id`, passed only for a piece's own attribute (an
+        # argument or a parameter carries no value-object type at all — see
+        # entity.bluebook's/command.bluebook's own comments on why — so the
+        # generic reader path calls this with one argument and gets the
+        # OLD reading unchanged), is the piece's OWNING aggregate — the same
+        # one its own attribute types were resolved against on the way in
+        # (`Judge#owning_aggregate_ref`).
+        #
+        # A REFERENCE among the other two came in as the head's ID, because
+        # that is what Command/Query.Reference offer, so it goes back out as
+        # the encoding the IR spells. A qualified name is the tell : an
+        # ordinary type names something declared beside it (`Money`,
+        # `AccountNumber`) and never carries a chapter, while a head's id
+        # always does.
+        def shape_field(field, aggregate_id = nil)
+          return attribute(field, aggregate_id) if aggregate_id
+
           type = text(field[:type]).to_s
 
           {
@@ -221,9 +240,10 @@ module Hecks
         # language does not hold is a named gap, not a byte-for-byte one).
         def mutation(target, op, bindings)
           base = { target: target.to_sym, op: op.to_sym, sign: Hecks::Bluebook::Mutation.sign_for(op) }
-          # `:delegate` (CommandBuilder#delegates_to's own comment) rides
-          # the SAME multi-binding shape `:append` does.
-          return base.merge(fields: appended(bindings)) if ["append", "delegate"].include?(op)
+          # `:delegate`/`:corrects` (CommandBuilder#delegates_to's and
+          # #corrects_impl's own comments) ride the SAME multi-binding
+          # shape `:append` does.
+          return base.merge(fields: appended(bindings)) if ["append", "delegate", "corrects"].include?(op)
 
           base.merge(source: classified(bindings.first))
         end

data/lib/hecks/bluebook/meta_validator.rb

@@ -8,16 +8,39 @@ module Hecks
     # `lib/hecks/language/bluebook/` declares what a bluebook IS —
     # Chapter, Root, Verb, Shape, Ask, Piece, and the rest, split across files
     # by domain concept and merged into one chapter at load time (see
-    # GRAMMAR_FILES below) — and carries the language's rules as `given` and
-    # `invariant` rather than as `raise Malformed` scattered across seven
-    # builder files. This replays a built IR into that domain and turns any
-    # refusal into a Malformed, so the meta-domain is what actually judges
-    # rather than a description sitting beside the code.
+    # GRAMMAR_FILES below). This replays a built IR into that domain and turns
+    # any refusal into a Malformed, so the meta-domain is what actually judges
+    # rather than a description sitting beside the code — for whatever rules
+    # it carries. `spec/meta_rules_spec.rb`'s own header names the plan: port
+    # the language's rules OUT of builder `raise Malformed` calls and INTO
+    # `given`/`invariant` here, where they are declarations any reader of the
+    # meta-domain can consume instead of behavior buried in a builder.
     #
-    # Delete language/bluebook/ and validation stops. That is the whole
-    # point : a self-description that only describes is indistinguishable from
-    # enforcement, and the first version of this file was deleted for exactly
-    # that reason.
+    # THIS MIGRATION IS PARTIAL, NOT DONE. As of this writing the meta-domain
+    # declares 62 given/invariant/ensures rules (`Hecks::QueryIR.collect_rules`
+    # against `grammar_registry.bluebook("Bluebook")` enumerates them) —
+    # `spec/meta_rule_reachability_spec.rb` is what proves, per declaration,
+    # not per verb, that most of them still lack a spec exercising the
+    # refusal at all (see that file's own KNOWN_GAPS for the current count).
+    # Meanwhile `lib/hecks/bluebook/dsl/` still carries well over a hundred
+    # `raise Malformed` calls of its own — some are genuinely pre-IR
+    # construction errors (arity, argument shape) that cannot become
+    # meta-domain rules, and some are exactly the semantic kind this file
+    # claims to have moved (see `aggregate_builder.rb`'s `seal_*` passes:
+    # a mutation into a field the aggregate never declares, a lifecycle guard
+    # on an aggregate with no lifecycle). No doc currently inventories which
+    # is which, or tracks migrating the latter — that inventory is the actual
+    # next step, not a "delete the folder" thought experiment.
+    #
+    # So: "delete language/bluebook/ and validation stops" is true for the 62
+    # rules actually declared here, and false for whatever a builder's own
+    # `raise Malformed` still checks — the language does not yet own its own
+    # enforcement end to end, and this comment used to claim it already did.
+    # The self-hosting mechanism itself is real and is the point worth
+    # keeping : a self-description that only describes is indistinguishable
+    # from enforcement, and the first version of this file was deleted for
+    # exactly that reason. What is not yet real is that self-hosting being
+    # the WHOLE of validation.
     #
     # The meta-domain is loaded ONCE and its registry reused ; each bluebook is
     # judged in a fresh in-memory store so no domain can see another's records.
@@ -131,6 +154,12 @@ module Hecks
           # dead code, never actually invoked.
           builder = registry.bluebook_builder(name) { raise "internal: no open builder for #{name}" }
           builder.resolve_pending_chapter_givens!
+          # THE ENTITY-SCOPED ANALOGUE, one level down — same reason,
+          # same timing: a bare entity-level given left PENDING by any
+          # file of this chapter (`EntityBuilder#pending_chapter_entity_
+          # given`) must resolve before anything below reads a piece's
+          # own `Given` fields too.
+          builder.resolve_pending_chapter_entity_givens!
 
           # `BluebookBuilder#build` skipped its own whole-chapter battery
           # (hops, projected fields, correlation keys, event shapes,
@@ -147,7 +176,48 @@ module Hecks
         end
       end
 
-      def self.disabled? = ENV["HECKS_META_VALIDATION"] == "off"
+      # `&& !@forcing_fixpoint` — see `while_forcing_fixpoint` below, whose own
+      # window must win even while a growth spec's `while_disabled` is open,
+      # for the reason recorded there. Otherwise the SAME stack-restore shape
+      # `while_shadow_parsing`/`while_forcing_fixpoint` use, not a bare env
+      # toggle any more — it used to be exactly that (`ENV["HECKS_META_
+      # VALIDATION"] == "off"`, read directly, with no `previous`/`ensure` of
+      # its own), and the gap between "bare toggle" and "stack-restore" was
+      # not cosmetic: a test's temporary window could reach code it was never
+      # meant to touch. If `grammar_registry`'s ONE-TIME lazy build (below)
+      # happened to land inside that window, EVERY language chapter got
+      # cached in its raw, never-judged form for the rest of the process —
+      # `unmark_scalar`'s String->Integer/Boolean fix (assembly/marks.rb)
+      # never ran, so a `Command`'s own `required: true` stayed
+      # `required: "true"` forever after, permanently memoized. Found live:
+      # an intermittent, parallel_rspec-only ir_golden_spec.rb failure,
+      # order-dependent on whether identifier_numeric_coercion_growth_spec.rb's
+      # disabled-validation window raced the ONE lazy build in its own worker
+      # process — reproduced in isolation by disabling validation before the
+      # first `grammar_registry` call. `&& !@forcing_fixpoint` was the first
+      # fix and is kept ; converting `@disabled` itself to this shape closes
+      # the gap for every OTHER caller of `while_disabled`, not just the one
+      # race that was actually observed — nothing outside this file reads
+      # `ENV["HECKS_META_VALIDATION"]` any more (confirmed: every one of the
+      # dozen growth specs that used to hand-roll `previous = ENV[...] ;
+      # ENV[...] = "off" ; ... ; ensure ENV[...] = previous` now calls
+      # `while_disabled` instead), so there is no bare global left to race.
+      def self.disabled? = @disabled && !@forcing_fixpoint
+
+      # THE SAME STACK-RESTORE SHAPE `while_shadow_parsing`/`while_forcing_
+      # fixpoint` USE. This toggle's real, intended use is a growth spec
+      # that boots a scratch bluebook from a tempfile and wants the runtime
+      # behaviour without the validation overhead ; that is always a single
+      # bounded window around one boot, never a flag meant to survive past
+      # it, so the flag itself is scoped in the same `previous`/`ensure`
+      # shape rather than a plain assignment a caller could forget to undo.
+      def self.while_disabled
+        previous  = @disabled
+        @disabled = true
+        yield
+      ensure
+        @disabled = previous
+      end
 
       # ADR 0025's own prerequisite (docs/dsl-work-slices.md, S0a): a word
       # a later slice removes from the LIVE grammar must still parse
@@ -175,6 +245,21 @@ module Hecks
         @shadow_parsing = previous
       end
 
+      # THE SAME STACK-RESTORE SHAPE `while_shadow_parsing` USES, for the
+      # same reason: whatever this wraps must never see `disabled?` answer
+      # true, however a test elsewhere has the env toggle set at that
+      # exact moment. Only `grammar_registry`'s own one-time build (below)
+      # wraps itself in this — nothing else needs it, and nothing else
+      # should reach for it just to dodge `disabled?` for a domain
+      # bluebook, which is precisely the toggle's real, intended use.
+      def self.while_forcing_fixpoint
+        previous          = @forcing_fixpoint
+        @forcing_fixpoint = true
+        yield
+      ensure
+        @forcing_fixpoint = previous
+      end
+
       # The same bluebook judged twice gets the same verdict, and a suite reloads
       # its fixtures constantly — banking alone is ~200 dispatches per build.
       # Keyed on the IR itself, so a CHANGED bluebook is always re-judged.
@@ -348,9 +433,14 @@ module Hecks
           # judged from here on is judged by the language the language itself
           # produced. Outside load_grammar_into on purpose : its ensure clears
           # @bootstrapping, and call() must see bootstrapping? == false to do
-          # anything at all.
-          LANGUAGE_CHAPTERS.each { |name| registry.add_bluebook(call(registry.bluebook(name))) }
-          load_attached_grammar_into(registry)
+          # anything at all. `while_forcing_fixpoint`-wrapped so a growth
+          # spec's own `while_disabled` window can never leave this
+          # ONE-TIME build cached in its raw, never-judged form — see
+          # `disabled?`'s own comment.
+          while_forcing_fixpoint do
+            LANGUAGE_CHAPTERS.each { |name| registry.add_bluebook(call(registry.bluebook(name))) }
+            load_attached_grammar_into(registry)
+          end
           # Stamped LAST, keyed by this registry's own identity rather than
           # a bare boolean — a manual reset (fixpoint_spec.rb's own
           # `@grammar_registry = nil`) makes @grammar_registry not equal

data/lib/hecks/bluebook/model_check.rb

@@ -46,18 +46,51 @@ module Hecks
       # 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.
-      ALLOWED_FINDINGS = {}.freeze
+      #
+      # "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.
+      ALLOWED_FINDINGS = {
+        "banking" => [
+          [:unacknowledged_relationship, "NotifyOnClosure"],
+          [:unknown_target_domain, "NotifyOnClosure"],
+          [:unacknowledged_relationship, "FlagKeyReturn"],
+          [:unknown_target_domain, "FlagKeyReturn"]
+        ]
+      }.freeze
 
       module_function
 
-      def call(bluebook)
+      # `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
+      # (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
+      # 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)
         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 { |pm| findings.concat(saga_findings(bluebook, pm)) }
-        bluebook.policies.each { |policy| findings.concat(policy_findings(bluebook, policy)) }
+        bluebook.policies.each { |policy| findings.concat(policy_findings(bluebook, policy, hecksagon, known_domains)) }
         findings
       end
 
@@ -151,7 +184,21 @@ module Hecks
       # forever, since nothing about *entering* it via default implies
       # anything must eventually move it, unlike a state a transition
       # explicitly delivered somewhere.
-      def terminal_exempt(_lifecycle) = []
+      #
+      # Scoped to `default` alone, and only when the lifecycle actually
+      # 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).
+      def terminal_exempt(lifecycle)
+        return [] if lifecycle.transitions.empty?
+
+        outgoing_sources = lifecycle.transitions.flat_map { |_, t| Array(t.from) }.to_set
+        outgoing_sources.include?(lifecycle.default) ? [] : [lifecycle.default]
+      end
 
       # ── process managers / sagas ──────────────────────────────────────
 
@@ -200,6 +247,23 @@ module Hecks
                                              "declares no command at — cross-domain dispatch is out of this " \
                                              "checker's scope, same as CommandRules#resolve_references")
           end
+
+          # 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 (`pm.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.
+          if !pm.saga? && handler.dispatches.any?(&:compensates)
+            handler.dispatches.select(&:compensates).each do |dispatch|
+              findings << Finding.new(kind: :unarmed_compensation, severity: :error, subject: pm.name,
+                                      message: "#{dispatch.command_name} compensates #{dispatch.compensates.command_name}, " \
+                                               "but no handler anywhere in this saga answers a refusal — the " \
+                                               "compensation is declared and can never fire")
+            end
+          end
         end
 
         if pm.saga? && !reached.include?(pm.saga.from_state)
@@ -240,8 +304,8 @@ module Hecks
 
       # ── policies ───────────────────────────────────────────────────────
 
-      def policy_findings(bluebook, policy)
-        return [] if policy.target_domain # cross-domain: CommandRules skips it too; so does this checker.
+      def policy_findings(bluebook, policy, hecksagon, known_domains)
+        return cross_domain_policy_findings(policy, hecksagon, known_domains) if policy.target_domain
 
         emitted = emitted_events(bluebook)
         findings = []
@@ -276,6 +340,83 @@ module Hecks
         findings
       end
 
+      # ── 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
+      # 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
+      # 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
+      # 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.
+      def cross_domain_policy_findings(policy, hecksagon, known_domains)
+        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
+          # 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
+          # `uses_framework` that isn't really doing what its name says.
+          findings << Finding.new(kind: :contradictory_relationship, severity: :error, subject: policy.name,
+                                  message: "across #{target.inspect} dispatches over RPC (Customer/Supplier), " \
+                                           "but this hecksagon also uses_framework #{target.inspect} (Shared " \
+                                           "Kernel) — #{target} is already loaded in-process here, so the two " \
+                                           "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
+          # 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`
+          # by number as failing the corpus-use bar; this is the real use.
+          findings << Finding.new(kind: :unacknowledged_relationship, severity: :error, subject: policy.name,
+                                  message: "across #{target.inspect} declares a Customer/Supplier " \
+                                           "relationship, but nothing in this hecksagon records the " \
+                                           "expectation — add subscribe \"#{target}.SomeEvent\" for what " \
+                                           "you expect back from it, or uses_framework #{target.inspect} to " \
+                                           "attach it in-process instead")
+        end
+
+        # 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
+        # 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."
+        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")
+        end
+
+        findings
+      end
+
       # ── shared enumeration ────────────────────────────────────────────
 
       # A PORT OPERATION EMITS TOO — the primary/driving port an adapter

data/lib/hecks/bluebook/pattern_subset.rb

@@ -66,6 +66,14 @@ module Hecks
       def validate(pattern)
         chars = pattern.to_s.chars
         index = 0
+        # 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 `[`
+        # or `[^` (where it is itself a literal, per POSIX bracket-expression
+        # rules).
+        in_class = false
+        class_start = nil
 
         while index < chars.length
           if chars[index] == "\\"
@@ -78,14 +86,36 @@ module Hecks
             next
           end
 
+          if in_class
+            if chars[index] == "]" && index != class_start
+              in_class = false
+              index += 1
+              next
+            end
+
+            return refuse(:posix_class) if posix_class_at?(chars, index)
+
+            index += 1
+            next
+          end
+
+          if chars[index] == "["
+            return refuse(:posix_class) if posix_class_at?(chars, index)
+
+            in_class = true
+            class_start = index + 1
+            class_start += 1 if chars[class_start] == "^"
+            index += 1
+            next
+          end
+
           if chars[index] == "(" && chars[index + 1] == "?"
             return refuse(:lookahead)    if %w[= !].include?(chars[index + 2])
             return refuse(:lookbehind)   if chars[index + 2] == "<" && %w[= !].include?(chars[index + 3])
             return refuse(:atomic_group) if chars[index + 2] == ">"
           end
 
-          return refuse(:posix_class)  if posix_class_at?(chars, index)
-          return refuse(:possessive)   if %w[* + ?].include?(chars[index]) && chars[index + 1] == "+"
+          return refuse(:possessive) if possessive_at?(chars, index)
 
           index += 1
         end
@@ -115,6 +145,40 @@ module Hecks
         cursor += 1 while chars[cursor]&.match?(/[a-zA-Z]/)
         chars[cursor] == ":" && chars[cursor + 1] == "]"
       end
+
+      # A possessive quantifier is `*+`, `++`, `?+`, or a bounded `{n}`/{n,m}`
+      # immediately followed by `+` — only checked OUTSIDE a character class,
+      # where `*`, `+`, `?`, `{`, `}` are quantifier syntax rather than
+      # literal characters.
+      def possessive_at?(chars, index)
+        return true if %w[* + ?].include?(chars[index]) && chars[index + 1] == "+"
+        return false unless chars[index] == "{"
+
+        len = bounded_quantifier_length(chars, index)
+        !len.nil? && chars[index + len] == "+"
+      end
+
+      # Length of a `{n}` / `{n,}` / `{n,m}` bound starting at `index`, or nil
+      # if what's there isn't one.
+      def bounded_quantifier_length(chars, index)
+        cursor = index + 1
+        digit_seen = false
+
+        while chars[cursor]&.match?(/[0-9]/)
+          digit_seen = true
+          cursor += 1
+        end
+        return nil unless digit_seen
+
+        if chars[cursor] == ","
+          cursor += 1
+          cursor += 1 while chars[cursor]&.match?(/[0-9]/)
+        end
+
+        return nil unless chars[cursor] == "}"
+
+        cursor - index + 1
+      end
     end
   end
 end