hecks 0.2.0 → 1.0.0

data/lib/hecks/bluebook/model_check.rb

@@ -0,0 +1,445 @@
+require "set"
+
+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
+    # 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
+    # code by hand ; this verifies the same IR the runtime dispatches
+    # against, so there is no second copy to drift.
+    module ModelCheck
+      Finding = Struct.new(:kind, :severity, :subject, :message, keyword_init: true) do
+        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
+      # 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
+      # constant, so the tool and the spec can never drift apart.
+      #
+      # "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
+      # 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
+      # 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
+      # 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.
+      ALLOWED_FINDINGS = {
+        "banking" => [
+          [:unacknowledged_relationship, "NotifyOnClosure"],
+          [:unknown_target_domain, "NotifyOnClosure"],
+          [:unacknowledged_relationship, "FlagKeyReturn"],
+          [:unknown_target_domain, "FlagKeyReturn"]
+        ]
+      }.freeze
+
+      module_function
+
+      # `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, hecksagon, known_domains)) }
+        findings
+      end
+
+      # ── lifecycles (aggregate AND entity — a piece may declare one too) ──
+
+      def lifecycle_findings(aggregate, declaring)
+        lifecycle = declaring.lifecycle
+        return [] unless lifecycle
+
+        subject = declaring.equal?(aggregate) ? aggregate.hecks_name : "#{aggregate.hecks_name}::#{declaring.hecks_name}"
+        commands = Array(declaring.commands).map(&:hecks_name)
+
+        findings = []
+        findings.concat(unknown_transition_commands(lifecycle, commands, subject))
+
+        full = full_states(lifecycle)
+        reached = reachable_states(lifecycle)
+
+        (full - reached.to_a).each do |state|
+          findings << Finding.new(kind: :unreachable_state, severity: :error, subject: subject,
+                                  message: "#{state.inspect} is declared (in a transition's from: or target) " \
+                                           "but no path from #{lifecycle.default.inspect} ever reaches it")
+        end
+
+        lifecycle.transitions.each do |command, transition|
+          next unless transition.constrained?
+          next if Array(transition.from).any? { |source| reached.include?(source) }
+
+          findings << Finding.new(kind: :dead_transition, severity: :error, subject: subject,
+                                  message: "#{command} from #{Array(transition.from).inspect} can never fire — " \
+                                           "none of those states is ever reached")
+        end
+
+        any_unconstrained = lifecycle.transitions.any? { |_, t| !t.constrained? }
+        (reached - terminal_exempt(lifecycle)).each do |state|
+          next if any_unconstrained
+          next if lifecycle.transitions.any? { |_, t| t.constrained? && Array(t.from).include?(state) }
+
+          findings << Finding.new(kind: :stuck_state, severity: :warning, subject: subject,
+                                  message: "#{state.inspect} is reached but no transition ever leaves it — " \
+                                           "fine if that is meant to be terminal")
+        end
+
+        findings
+      end
+
+      def unknown_transition_commands(lifecycle, commands, subject)
+        lifecycle.transitions.filter_map do |command, _transition|
+          next if commands.include?(command)
+
+          Finding.new(kind: :unknown_command, severity: :error, subject: subject,
+                      message: "a transition names #{command.inspect}, which this construct declares no command for")
+        end
+      end
+
+      # default, every declared target, and every declared from — a
+      # from-only state (declared nowhere as a target) is real and is
+      # exactly the hole `Lifecycle#states` leaves: it answers default
+      # plus targets only.
+      def full_states(lifecycle)
+        (
+          [lifecycle.default] +
+          lifecycle.transitions.map { |_, t| t.target } +
+          lifecycle.transitions.flat_map { |_, t| Array(t.from) }
+        ).uniq
+      end
+
+      # 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)
+        reached = Set.new([lifecycle.default])
+        loop do
+          grown = false
+          lifecycle.transitions.each do |_, transition|
+            next if reached.include?(transition.target)
+            next if transition.constrained? && Array(transition.from).none? { |source| reached.include?(source) }
+
+            reached << transition.target
+            grown = true
+          end
+          break unless grown
+        end
+        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
+      # 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
+      # anything must eventually move it, unlike a state a transition
+      # explicitly delivered somewhere.
+      def terminal_exempt(_lifecycle) = []
+
+      # ── process managers / sagas ──────────────────────────────────────
+
+      def saga_findings(bluebook, pm)
+        findings = []
+        emitted  = emitted_events(bluebook)
+        verbs    = verbs_of(bluebook)
+
+        [pm.starts_on, pm.ends_on].compact.each do |event|
+          next if emitted.include?(bare(event))
+
+          findings << Finding.new(kind: :deaf_trigger, severity: :error, subject: pm.name,
+                                  message: "starts_on/ends_on names #{event.inspect}, which no command in this " \
+                                           "domain emits")
+        end
+
+        reached = pm_reachable_states(pm, emitted)
+        (Array(pm.states) - reached.to_a).each do |state|
+          findings << Finding.new(kind: :unreachable_pm_state, severity: :error, subject: pm.name,
+                                  message: "#{state.inspect} is declared but no handler chain from " \
+                                           "#{pm.states.first.inspect} ever reaches it")
+        end
+
+        pm.handlers.each do |handler|
+          # 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))
+            findings << Finding.new(kind: :deaf_handler, severity: :error, subject: pm.name,
+                                    message: "a handler answers #{handler.event_type.inspect}, which no command " \
+                                             "in this domain emits")
+          end
+
+          handler.dispatches.each do |dispatch|
+            # SAME-DOMAIN, same as `SagaInterpreter#qualified` — a dispatch
+            # naming no domain at all (the ordinary shape a bare command
+            # constant now produces, S6) means THIS one, and is compared
+            # against `verbs_of`'s own fully-qualified spelling qualified
+            # the identical way, not left bare to miss it on a technicality.
+            qualified = dispatch.command_name.include?("::") ? dispatch.command_name : "#{bluebook.name}::#{dispatch.command_name}"
+            next if verbs.include?(qualified)
+
+            findings << Finding.new(kind: :unknown_dispatch, severity: :error, subject: pm.name,
+                                    message: "dispatches #{dispatch.command_name.inspect}, which this domain " \
+                                             "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)
+          findings << Finding.new(kind: :dead_compensation, severity: :error, subject: pm.name,
+                                  message: "the compensation leaves #{pm.saga.from_state.inspect}, which no " \
+                                           "handler chain ever reaches — a refusal here can never fire it")
+        end
+
+        findings
+      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
+      # 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).
+      def pm_reachable_states(pm, emitted)
+        return Set.new if Array(pm.states).empty?
+
+        reached = Set.new([pm.states.first])
+        loop do
+          grown = false
+          pm.handlers.each do |handler|
+            next unless handler.event_type == ProcessManager::REFUSED || emitted.include?(bare(handler.event_type))
+            next unless reached.include?(handler.from_state)
+            next if reached.include?(handler.to_state)
+
+            reached << handler.to_state
+            grown = true
+          end
+          break unless grown
+        end
+        reached
+      end
+
+      # ── policies ───────────────────────────────────────────────────────
+
+      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 = []
+
+        # `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
+        # "Account.AccountFrozen" against a list of bare emitted names that
+        # can never contain it. Latent until now : banking's one aggregate-
+        # scoped same-domain policy check would have caught it, but its only
+        # 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)
+          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
+
+        # `trigger` is spelled "Aggregate.Command" (or "Entity.Command" one
+        # level down), completed to an FQN by PolicyInterpreter#deliver as
+        # "#{domain}::#{trigger_command}" — the same join `verbs_of` builds
+        # independently, so the two spellings have to be compared as FQNs,
+        # never as bare command names.
+        unless verbs_of(bluebook).include?("#{bluebook.name}::#{policy.trigger_command}")
+          findings << Finding.new(kind: :unknown_trigger, severity: :error, subject: policy.name,
+                                  message: "trigger #{policy.trigger_command.inspect} resolves to no command " \
+                                           "this domain declares")
+        end
+
+        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
+      # 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`
+      # 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.
+      def emitted_events(bluebook)
+        aggregate_emits = bluebook.aggregates.flat_map do |aggregate|
+          aggregate.commands.map(&:emits) +
+            aggregate.entities.flat_map { |entity| entity.commands.map(&:emits) } +
+            aggregate.ports.flat_map { |port| port.operations.map(&:emits) }
+        end
+        chapter_emits = bluebook.ports.flat_map { |port| port.operations.map(&:emits) }
+
+        (aggregate_emits + chapter_emits).flatten.uniq
+      end
+
+      # Fully-qualified, the same spelling DispatchSpec#command_name
+      # 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.
+      def verbs_of(bluebook)
+        bluebook.aggregates.flat_map do |aggregate|
+          verbs = aggregate.commands.map { |command| "#{bluebook.name}::#{aggregate.hecks_name}.#{command.hecks_name}" }
+          verbs + aggregate.entities.flat_map do |entity|
+            entity.commands.map { |command|
+              "#{bluebook.name}::#{aggregate.hecks_name}.#{entity.hecks_name}.#{command.hecks_name}"
+            }
+          end
+        end
+      end
+
+      def bare(event) = event.to_s.split("::").last
+    end
+  end
+end

data/lib/hecks/bluebook/pattern_subset.rb

@@ -0,0 +1,184 @@
+module Hecks
+  module Bluebook
+    # 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,
+    #   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
+    #   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
+    # (Ruby's reading). The evidence is spec/corpus/fixtures/patterns.json.
+    module PatternSubset
+      Rejection = Struct.new(:construct, :reason)
+
+      REASONS = {
+        backreference:
+                             "backreferences cannot be matched in linear time and portable " \
+                             "engines refuse them ; a declared pattern may not depend on one",
+        named_backreference:
+                             "a named backreference is still a backreference — it cannot be " \
+                             "matched in linear time ; a declared pattern may not depend on one",
+        perl_class:
+                             "engines read it in OPPOSITE directions : ASCII in some and " \
+                             "Unicode in others, so an Arabic-Indic digit satisfies one and not " \
+                             "the other. Spell the range you mean — [0-9], [A-Za-z0-9_], [ \t] " \
+                             "— which every engine reads the same way",
+        posix_class:
+                             "[:digit:] and friends flip between ASCII and Unicode across " \
+                             "engines — the mirror of the perl classes, and wrong in the same " \
+                             "way. Spell the range you mean",
+        lookahead:
+                             "lookahead cannot be matched in linear time and portable engines " \
+                             "refuse it ; a declared pattern may not depend on it",
+        lookbehind:
+                             "lookbehind cannot be matched in linear time and portable engines " \
+                             "refuse it ; a declared pattern may not depend on it",
+        atomic_group:
+                             "an atomic group is a backtracking-engine control knob — " \
+                             "linear-time engines reject `(?>` as a syntax error",
+        possessive:
+                             "a possessive quantifier is a backtracking-engine control knob — " \
+                             "linear-time engines reject it as a syntax error"
+      }.freeze
+
+      module_function
+
+      # nil when the pattern is admitted, a Rejection when it is not.
+      #
+      # 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
+      # characters "(?=" and says nothing about lookahead — which is why this
+      # steps over each backslash pair rather than matching the pattern as a
+      # whole.
+      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] == "\\"
+            nxt = chars[index + 1]
+            return refuse(:backreference)        if nxt&.match?(/[1-9]/)
+            return refuse(:named_backreference)  if %w[k g].include?(nxt)
+            return refuse(:perl_class)           if %w[d D w W s S].include?(nxt)
+
+            index += nxt ? 2 : 1
+            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(:possessive) if possessive_at?(chars, index)
+
+          index += 1
+        end
+
+        nil
+      end
+
+      # SPELLED OUT, not derived from the key : these strings are the refusal
+      # a caller reads.
+      CONSTRUCTS = {
+        backreference:       "backreference",
+        named_backreference: "named backreference",
+        perl_class:          "perl character class",
+        posix_class:         "posix bracket class",
+        lookahead:           "lookahead",
+        lookbehind:          "lookbehind",
+        atomic_group:        "atomic group",
+        possessive:          "possessive quantifier"
+      }.freeze
+
+      def refuse(key) = Rejection.new(CONSTRUCTS.fetch(key), REASONS.fetch(key))
+
+      def posix_class_at?(chars, index)
+        return false unless chars[index] == "[" && chars[index + 1] == ":"
+
+        cursor = index + 2
+        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

data/lib/hecks/bluebook/policy.rb

@@ -0,0 +1,41 @@
+# 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"
+
+module Hecks
+  module Bluebook
+    class Policy
+      include Hecks::IR
+      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)] } }
+      )
+
+      attr_reader :name, :on_event, :trigger_command, :target_domain, :where, :for_each, :with_spec
+
+      # 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)
+        @name = name.to_s
+        @on_event = on_event
+        @trigger_command = trigger_command
+        @target_domain = target_domain
+        @where = where
+        @for_each = for_each
+        @with_spec = with_spec
+        @aggregate = aggregate&.to_s
+      end
+    end
+  end
+end