hecks 1.0.2 → 1.2.0

data/lib/hecks/bluebook/dsl/process_manager_builder.rb

@@ -2,8 +2,15 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
+      # Parses a `process_manager "Name" do ... end` block into a
+      # `ProcessManager` — its own `starts_on`/`ends_on` events, what
+      # correlates its instances (`correlates_by`), and the `transition`-
+      # declared state machine whose `dispatch`es (each optionally paired
+      # with its own per-dispatch `compensates`) become its handlers. States
+      # are DERIVED from the transitions rather than declared separately
+      # (S7, ADR 0025).
       class ProcessManagerBuilder
-        GRAMMAR_CONTEXT = "ProcessManager"
+        GRAMMAR_CONTEXT = "ProcessManager".freeze
 
         class InvalidProcessManager < StandardError; end
 
@@ -189,8 +196,10 @@ module Hecks
         end
 
         def validate!
-          raise InvalidProcessManager, "#{@name} declares no correlates_by — " \
-                                       "nothing would tie its events to one instance" unless @correlates_by
+          unless @correlates_by
+            raise InvalidProcessManager, "#{@name} declares no correlates_by — " \
+                                         "nothing would tie its events to one instance"
+          end
 
           # THE FIELD, NAMED — never the value object that carries it. A bare
           # `correlates_by :end_to_end` reads whatever the payload holds under
@@ -202,19 +211,54 @@ module Hecks
           # holds a head to. This is a syntactic check, not a type check: it
           # does not know or care whether the field IS a value object, only
           # that the declaration cannot leave that question open.
-          raise InvalidProcessManager, "#{@name} correlates_by #{@correlates_by.inspect}, which names a whole " \
-                                       "field rather than one of its scalars — say which one, e.g. " \
-                                       "#{@correlates_by}.value" unless @correlates_by.to_s.include?(".")
+          unless @correlates_by.to_s.include?(".")
+            raise InvalidProcessManager, "#{@name} correlates_by #{@correlates_by.inspect}, which names a whole " \
+                                         "field rather than one of its scalars — say which one, e.g. " \
+                                         "#{@correlates_by}.value"
+          end
+
+          if @starts_on.to_s.empty?
+            raise InvalidProcessManager, "#{@name} declares no starts_on — " \
+                                         "nothing would ever begin it"
+          end
+
+          if @handlers.empty?
+            raise InvalidProcessManager, "#{@name} declares no transitions — " \
+                                         "it would start and then ignore every event"
+          end
 
-          raise InvalidProcessManager, "#{@name} declares no starts_on — " \
-                                       "nothing would ever begin it" if @starts_on.to_s.empty?
+          refuse_ambiguous_legs!
+        end
 
-          raise InvalidProcessManager, "#{@name} declares no transitions — " \
-                                       "it would start and then ignore every event" if @handlers.empty?
+        # C10.3 — a leg is selected by (event, current state), so two
+        # legs answering the SAME event from the SAME state would leave
+        # the runtime to pick by declaration order, silently. Refused
+        # here, where the declaration can still be read whole. (`from:
+        # [...]` fan-out counts: `transition E => "a", from: ["x", "y"]`
+        # and `transition E => "b", from: "y"` collide on ("E", "y").)
+        def refuse_ambiguous_legs!
+          return if MetaValidator.shadow_parsing? # frozen era text is history
+
+          seen = {}
+          @handlers.each do |handler|
+            key = [handler.event_type, handler.from_state]
+            if (earlier = seen[key])
+              raise InvalidProcessManager,
+                    "#{@name} declares two transitions on #{handler.event_type.inspect} from " \
+                    "#{handler.from_state.inspect} (=> #{earlier.to_state.inspect} and => " \
+                    "#{handler.to_state.inspect}) — a leg is selected by (event, current state), so " \
+                    "only one may answer"
+            end
+            seen[key] = handler
+          end
         end
 
+        # THE BODY OF ONE `transition ... do ... end` block — collects the
+        # `dispatch` calls (each optionally opening its own `compensates`
+        # via the nested `DispatchBuilder`) that fire when this transition
+        # is taken.
         class HandlerBuilder
-          GRAMMAR_CONTEXT = "Handler"
+          GRAMMAR_CONTEXT = "Handler".freeze
 
           attr_reader :dispatches
 
@@ -282,7 +326,7 @@ module Hecks
           # any saga dispatch already does
           # (`SagaInterpreter#dispatch_args`).
           class DispatchBuilder
-            GRAMMAR_CONTEXT = "Dispatch"
+            GRAMMAR_CONTEXT = "Dispatch".freeze
 
             include WordGate
 

data/lib/hecks/bluebook/dsl/query_builder.rb

@@ -2,8 +2,14 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
+      # Parses a `query "Name" do ... end` block, declared on an aggregate
+      # or one of its entities, into a `Query` — its own parameters (plain
+      # attributes, including reference-typed ones) plus whatever `where`/
+      # `order_by`/`limit`/etc. `QuerySpecification::Common::DSL` contributes.
+      # A block parameter naming an already-declared owner attribute has its
+      # type derived from the owner rather than restated (`derive_from_owner!`).
       class QueryBuilder
-        GRAMMAR_CONTEXT = "Query"
+        GRAMMAR_CONTEXT = "Query".freeze
 
         include AttributeCollector
         include QuerySpecification::Common::DSL

data/lib/hecks/bluebook/dsl/read_model_builder.rb

@@ -2,8 +2,14 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
+      # Parses a `read_model "Name" do ... end` block into a `ReadModel` — a
+      # cross-aggregate projection built from an optional `reference_to`
+      # root (omitted, it's a rootless "bulk" read model) plus one or more
+      # `include`d aggregate heads, with `where`/`order_by`/`limit`/etc, and
+      # at most one of `group_by`, `count`, or `median` as its single
+      # reduction over the one eligible many-side collection.
       class ReadModelBuilder
-        GRAMMAR_CONTEXT = "ReadModel"
+        GRAMMAR_CONTEXT = "ReadModel".freeze
 
         include QuerySpecification::Common::DSL
         include WordGate
@@ -48,6 +54,72 @@ module Hecks
           @includes << [Naming.demodulise(type), as]
         end
 
+        # `on:` (ADR 0055) — OVERRIDES of `QuerySpecification::Common::DSL`'s
+        # shared `where_impl`/`order_by_impl`/`limit_impl`/`offset_impl`,
+        # scoped to `ReadModelBuilder` alone rather than added to the shared
+        # module `Query` also mixes in: a plain `query` has no
+        # `aggregate_heads` at all, so `on:` there would be a silently-
+        # ignored no-op rather than a real answer. Overriding only here
+        # means a `Query`'s own `where(..., on: X)` gets Ruby's own loud
+        # `unknown keyword: :on` instead of quietly doing nothing.
+        #
+        # `on:` names the target by TYPE (`on: Character`), resolved the
+        # same way `reference_to`/`include` already resolve their own type
+        # argument (`Naming.demodulise`) — not by the include's own `as:`
+        # alias. A read model that `include`s the SAME type twice under two
+        # different `as:` has no way to say which one `on:` means today; no
+        # real corpus read model does this, so it's a real, deliberate scope
+        # limit (see ADR 0055), not an oversight.
+        #
+        # `*positional, on:, **rest` rather than a plain `(clauses, on: nil)`
+        # — found necessary, not stylistic, by reproducing the failure
+        # directly: `where(status: "disputed")` reaches here with its
+        # `status: "disputed"` captured as `**kwargs` (GenericDispatch's own
+        # `builder.send(calls, *args, **kwargs, &block)`), and Ruby stops
+        # auto-converting a bare `**hash` call into a plain positional Hash
+        # THE MOMENT a method declares any real keyword parameter — so a
+        # `(clauses, on: nil)` signature raised "wrong number of arguments
+        # (given 0, expected 1)" on every ordinary `where(field: value)`
+        # call, never reaching `on:` at all. `**rest` sidesteps this: Ruby
+        # still auto-splits `on:` into the declared keyword and gathers
+        # every OTHER key into `rest` regardless of how the caller wrote it.
+        #
+        # `QuerySpecification::Common::WhereClause` etc — FULLY QUALIFIED,
+        # not the bare names `dsl.rb`'s own shared `where_impl` gets away
+        # with. That file is lexically nested inside `Common` itself, so
+        # `WhereClause` resolves directly; this class is nested inside
+        # `Bluebook::DSL`, which has no lexical or ancestor path to
+        # `QuerySpecification::Common` at all — a bare `WhereClause` here
+        # falls through to `const_missing` and, mid-bluebook-load, that's
+        # `ConstShim`, which resolves it against the self-hosted grammar
+        # domain's OWN unrelated `WhereClause` construct instead (a `Module`,
+        # not this `Struct`) — found directly by reproducing "undefined
+        # method `new' for module WhereClause" against a real corpus load,
+        # not guessed.
+        def where_impl(*positional, on: nil, **rest)
+          raise ArgumentError, "wrong number of arguments (given #{positional.size}, expected 1)" if positional.size > 1
+
+          @wheres ||= []
+          target = resolve_target(on)
+          clauses = (positional.first || {}).merge(rest)
+          clauses.each do |field, value|
+            op, operand = split_comparator(value)
+            @wheres << QuerySpecification::Common::WhereClause.new(field: field, op: op, value: operand, target: target)
+          end
+        end
+
+        def order_by_impl(field, direction = :asc, on: nil)
+          @order_by = QuerySpecification::Common::OrderBy.new(field: field, direction: direction, target: resolve_target(on))
+        end
+
+        def limit_impl(value, on: nil)
+          @limit = QuerySpecification::Common::LimitSpec.new(value: value, target: resolve_target(on))
+        end
+
+        def offset_impl(value, on: nil)
+          @offset = QuerySpecification::Common::OffsetSpec.new(value: value, target: resolve_target(on))
+        end
+
         # NAMES which of the eligible head's own fields to nest its rows
         # under — one level per field, the leaf being that row with the
         # named fields removed (they're already spent, as the keys that
@@ -107,8 +179,10 @@ module Hecks
         # field values) has no root to speak of. Still needs to describe
         # SOMETHING — zero includes AND no reference is refused.
         def build
-          raise Malformed,
-                "#{@name} needs an aggregate-head reference or at least one include" if !@reference_target && Array(@includes).empty?
+          if !@reference_target && Array(@includes).empty?
+            raise Malformed,
+                  "#{@name} needs an aggregate-head reference or at least one include"
+          end
 
           Array(@includes).each do |target, as|
             add_aggregate_head(target, as, many: target != @reference_target)
@@ -134,27 +208,70 @@ module Hecks
 
         private
 
-        # where/order_by/limit/offset/authorize's tenant all apply to exactly
-        # one collection — the single `include`d aggregate whose head is
-        # "many" (the "one" side, the reference target itself, is a single
-        # row; ordering, paging, or tenant-scoping one row means nothing). A
-        # read model with zero many-heads has nothing for them to filter ;
-        # one with several has no way to say WHICH of several unrelated
-        # collections a caller meant — so both refuse here rather than
-        # silently applying to an arbitrary one. `authorize`'s tenant counts
-        # here too — TenantScope enforces it against this same head, so an
-        # ambiguous target is exactly as unusable as it is for the others.
+        # where/order_by/limit/offset/authorize's tenant all apply to
+        # collections — the `include`d aggregates whose heads are "many"
+        # (the "one" side, the reference target itself, is a single row;
+        # ordering, paging, or tenant-scoping one row means nothing). ADR
+        # 0055 gave `where`/`order_by`/`limit`/`offset` an `on:` to name
+        # WHICH many-side collection they mean, so this asks two questions
+        # now instead of one:
+        #
+        #   1. Does every declared `on:` actually name a many-side included
+        #      aggregate? Checked regardless of how many many-side heads
+        #      exist — a typo refuses immediately, not only once ambiguity
+        #      would otherwise bite.
+        #   2. Is there still an UNTARGETED option declared (including
+        #      `authorize`'s own `tenant:`, which has no `on:` of its own —
+        #      a real, deliberate scope limit, see ADR 0055)? An untargeted
+        #      option still needs exactly one many-side head to mean
+        #      anything unambiguous — the ORIGINAL rule, unchanged, and
+        #      still worded the same way (`spec/runtime/
+        #      read_model_interpreter_spec.rb`'s existing refusal regex
+        #      still matches).
+        #
+        # A read model with several many-side heads is legal precisely when
+        # every declared option names one; a read model with a single
+        # many-side head is unaffected either way, `on:` or not.
         def seal_query_options
-          declared = @wheres&.any? || @order_by || @limit || @offset || @authorization&.tenant
-          return unless declared
+          many = Array(@aggregate_heads).select { |head| head[:many] }
 
-          many = Array(@aggregate_heads).count { |head| head[:many] }
-          return if many == 1
+          validate_declared_targets!(many)
+          return unless untargeted_option_declared?
+          return if many.size == 1
 
           raise Malformed,
-                "#{@name} declares where/order_by/limit/offset but includes #{many} many-side " \
+                "#{@name} declares where/order_by/limit/offset but includes #{many.size} many-side " \
                 "aggregates, not exactly one — these options apply to a single collection; " \
-                "name which one by including only it, or drop the options"
+                "name which one with `on:` (e.g. `where(field: value, on: Character)`), or drop the options"
+        end
+
+        # Question 1 of `seal_query_options`'s own two, split out to keep
+        # both under the same "one job per method" shape every OTHER seal in
+        # this file already holds to (each raises its own one Malformed, for
+        # its own one reason).
+        def validate_declared_targets!(many)
+          many_by_aggregate = many.to_h { |head| [head[:aggregate], head] }
+          declared_targets = Array(@wheres).map(&:target) + [@order_by&.target, @limit&.target, @offset&.target]
+
+          declared_targets.compact.uniq.each do |target|
+            next if many_by_aggregate.key?(target)
+
+            raise Malformed,
+                  "#{@name}'s `on: #{target}` doesn't name one of its own many-side included " \
+                  "aggregates (it includes #{many.map { |head| head[:aggregate] }.join(', ')} as " \
+                  "many-side heads)"
+          end
+        end
+
+        # Question 2 of `seal_query_options`'s own two — see that method's
+        # header. `authorize`'s own `tenant:` has no `on:` at all (ADR 0055's
+        # own documented scope limit), so it always counts as untargeted.
+        def untargeted_option_declared?
+          Array(@wheres).any? { |where| where.target.nil? } ||
+            (@order_by && @order_by.target.nil?) ||
+            (@limit && @limit.target.nil?) ||
+            (@offset && @offset.target.nil?) ||
+            @authorization&.tenant
         end
 
         # Same shape as `seal_query_options`, same reason — `group_by`
@@ -219,6 +336,12 @@ module Hecks
                 "pagination — use limit/offset instead"
         end
 
+        # `on:`'s own resolution (ADR 0055) — same demodulise `reference_to`/
+        # `include` already use for their own type argument. `nil` when `on:`
+        # is omitted, matching every other optional field's "absent, not
+        # false" reading in this file.
+        def resolve_target(on) = on && Naming.demodulise(on)
+
         def add_aggregate_head(type, name, many:)
           @aggregate_heads ||= []
           target = Naming.demodulise(type)

data/lib/hecks/bluebook/dsl/rule_reference.rb

@@ -59,7 +59,9 @@ module Hecks
                   "extraction — #{extraction_failure}"
           end
 
-          struct_class.new(description: description, canonical: canonical, predicate: predicate)
+          ast = Expression::AstJson.refuse_unshared_patterns!(Expression::AstJson.emit_predicate(canonical),
+                                                              owner: owner_name, word: "#{word} #{description.inspect}")
+          struct_class.new(description: description, canonical: canonical, predicate: predicate, ast: ast)
         end
 
         # PRIMITIVE 1 — an ORDERED CHAIN of flat `Hash[description] =>

data/lib/hecks/bluebook/dsl/translation_builder.rb

@@ -2,8 +2,14 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
+      # Parses an `aggregate "Name" do ... end` block inside a `.translation`
+      # file into a `TranslationAggregate` — the per-aggregate rules
+      # (`rename`/`move`/`convert`/`retype`/`compute`/`rekey`/`backfill`/
+      # `drop`) that carry one era's stored data forward to the next, plus
+      # `unresolved` markers the scaffold writes wherever it cannot decide a
+      # rule for itself.
       class TranslationAggregateBuilder
-        GRAMMAR_CONTEXT = "TranslationAggregate"
+        GRAMMAR_CONTEXT = "TranslationAggregate".freeze
 
         include WordGate
 
@@ -183,8 +189,13 @@ module Hecks
         end
       end
 
+      # Parses a whole `.translation` file into a `Translation` — the
+      # domain's own `from:`/`to:` era pair, its list of `aggregate`
+      # translation blocks (each built by `TranslationAggregateBuilder`
+      # above), and any `retired` aggregates that no longer exist in the
+      # destination era.
       class TranslationBuilder
-        GRAMMAR_CONTEXT = "Translation"
+        GRAMMAR_CONTEXT = "Translation".freeze
 
         include WordGate
 

data/lib/hecks/bluebook/dsl/value_object_builder.rb

@@ -2,8 +2,15 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
+      # Parses a `value_object "Name" do ... end` block into a
+      # `ValueObject` — its attributes, its own invariants (declared once
+      # and referenceable by name from sibling value objects on the same
+      # aggregate, `RuleReference`), and its `member` rows when it's a
+      # closed set (either bare `one_of` member lines, or the single-field
+      # `attribute ..., one_of: [...]` shorthand `install_inline_closed_set`
+      # installs).
       class ValueObjectBuilder
-        GRAMMAR_CONTEXT = "ValueObject"
+        GRAMMAR_CONTEXT = "ValueObject".freeze
 
         include AttributeCollector
         include RuleReference

data/lib/hecks/bluebook/dsl/word_gate.rb

@@ -150,6 +150,11 @@ module Hecks
         # admitted-but-unimplemented, or admitted-somewhere-else-only —
         # those are real, useful refusals regardless of which
         # `method_missing` is asking.
+        # One ordered admission-then-dispatch pipeline (own context, then
+        # "Type" fallback, then admitted-elsewhere check, then dispatch) —
+        # see this method's own header comment above for the full,
+        # order-dependent account of why each check runs where it does.
+        # rubocop:disable-next Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         def word_gate_dispatch(word, args, kwargs, block)
           context = self.class::GRAMMAR_CONTEXT
           rows = MetaValidator::SyntaxBoot.call

data/lib/hecks/bluebook/dsl/world_builder.rb

@@ -2,10 +2,15 @@ require_relative "word_gate"
 module Hecks
   module Bluebook
     module DSL
+      # A generic keyword-call sink for one bind's own settings block (e.g.
+      # `persisted_by "Heki" do dir :default end`) — every method call made
+      # on it inside the block is recorded verbatim by name, with no fixed
+      # vocabulary of its own; `WorldBuilder#record_binding` reads `#to_h`
+      # back out.
       class SettingsCollector
         def initialize = @values = {}
 
-        def method_missing(key, *args, &_block)
+        def method_missing(key, *args, &)
           @values[key.to_sym] = args.size == 1 ? args.first : args
         end
 
@@ -38,8 +43,13 @@ module Hecks
         def respond_to_missing?(_name, _include_private = false) = true
       end
 
+      # Parses a `.world` file's top-level DSL block into a `World` — a
+      # domain's own `realm`/`latest` version markers plus its adapter bind
+      # SETTINGS, one entry per `verb("Adapter") do ... end` call (whether
+      # written bare or aggregate-qualified through `WorldConstProxy`'s
+      # visual mirror of a sibling `.hecksagon` file's own bind).
       class WorldBuilder
-        GRAMMAR_CONTEXT = "World"
+        GRAMMAR_CONTEXT = "World".freeze
 
         include WordGate
 
@@ -107,7 +117,7 @@ module Hecks
 
         private
 
-        def required(value, label)
+        def required(value, _label)
           # moved to the language: Realm / Latest invariants, in world.bluebook
           value.to_s
         end

data/lib/hecks/bluebook/entity.rb

@@ -1,4 +1,5 @@
 require_relative "behaviour/entity"
+require_relative "expression/ast_json"
 
 module Hecks
   module Bluebook
@@ -51,7 +52,7 @@ module Hecks
         # documentation of what the piece itself declared, the same
         # relationship `Aggregate.preconditions` already has to its own
         # commands.
-        preconditions: -> { preconditions.map { |rule| { description: rule.description, canonical: rule.canonical } } },
+        preconditions: -> { preconditions.map { |rule| Expression::AstJson.rule_row(rule) } },
         # A piece's OWN shape rule, checked against EVERY instance of
         # this piece the aggregate holds (Admissibility#enforce_
         # invariants' own recursive walk) — the SAME relationship
@@ -61,7 +62,7 @@ module Hecks
         # mutation, before save) the aggregate's own invariants always
         # were — see that method's own comment for why this does not
         # contradict "there is no separate entity invariant."
-        invariants:    -> { invariants.map { |rule| { description: rule.description, canonical: rule.canonical } } },
+        invariants:    -> { invariants.map { |rule| Expression::AstJson.rule_row(rule) } },
         lifecycle:     one(:lifecycle)
       )
 
@@ -84,7 +85,8 @@ module Hecks
         # Assigns what the language declares, then hands off to the
         # behaviour's own `settle` — derived identity and the name
         # indexes, neither of which the declaration states.
-        def absorb(description:, identified_by:, attributes:, commands:, queries:, entities:, preconditions:, invariants:, lifecycle:)
+        def absorb(description:, identified_by:, attributes:, commands:, queries:, entities:, preconditions:, invariants:,
+                   lifecycle:)
           @description    = description
           @identified_by  = identified_by
           @attributes     = attributes

data/lib/hecks/bluebook/expression/ast_json.rb

@@ -42,8 +42,8 @@ module Hecks
       # `expr_emitter.rb`'s own `emit_bool`/`emit_resolver` already hold
       # to — even though, as of this writing, no real corpus VALUE OBJECT
       # invariant exercises `Include`/`Modulo`/`BlockPredicate`/`Find`/
-      # `Array`/`MatchesRegex`/`Presence`/`Split`/`StartsWith`/`EndsWith`/
-      # `First`/`Last` (only `given`/`ensures` clauses do, elsewhere in
+      # `Array`/`MatchesRegex`/`Presence`/`Assignment`/`Split`/`StartsWith`/
+      # `EndsWith`/`First`/`Last` (only `given`/`ensures` clauses do, elsewhere in
       # the corpus — a different consumer of this same grammar).
       # `rust/host/src/expr_json.rs`'s own header names exactly which of
       # these its interpreter evaluates for real today versus refuses
@@ -56,10 +56,75 @@ module Hecks
       module AstJson
         module_function
 
+        # THE CLOSED OP ROSTER — every `"op"` tag the walkers below can
+        # emit, pinned so a reader (or a spec) can refuse a tag it does
+        # not know instead of guessing. A new node kind is a new entry
+        # here, a new arm below, and a new arm in every reader.
+        OPS = %w[
+          or and not compare include
+          int float str bool nil array lookup
+          add modulo sign_test empty size to_s
+          block_predicate find first last
+          matches_regex presence assignment split starts_with ends_with
+        ].freeze
+
+        # ONE RULE ROW, THE WAY EVERY RULE SITE EMITS IT — description and
+        # canonical text (what every reader has always had) plus the
+        # structured form, derived from the same text. `ast` is a pure
+        # function of `canonical`: the IR carries both so a reader that
+        # only displays keeps the text, and a reader that evaluates never
+        # re-parses it.
+        def rule_row(rule)
+          { description: rule.description, canonical: rule.canonical, ast: rule.ast || emit_predicate(rule.canonical) }
+        end
+
         def emit_predicate(canonical)
           emit_bool(Evaluator.parse(canonical))
         end
 
+        # C3.6 (docs/semantics/bluebook-semantics.md) — every `.match?`
+        # pattern a rule carries is held to `PatternSubset`, exactly as an
+        # attribute's own `pattern:` already is (`AttributeCollector#
+        # refuse_unshared_pattern`): a regex whose meaning depends on the
+        # engine reading it is a defect in the bluebook, refused at build.
+        # Walks the emitted AST, so every rule site (givens, ensures,
+        # invariants, preconditions, a policy's where) gets the one check.
+        def refuse_unshared_patterns!(ast, owner:, word:)
+          return ast if Hecks::Bluebook::MetaValidator.shadow_parsing? # frozen era text is history
+
+          each_node(ast) do |node|
+            next unless node["op"] == "matches_regex"
+
+            rejection = PatternSubset.validate(node["pattern"])
+            next unless rejection
+
+            raise DSL::Malformed,
+                  "#{owner}'s #{word} matches against #{node['pattern'].inspect}, which uses a " \
+                  "#{rejection.construct} — #{rejection.reason}"
+          end
+          ast
+        end
+
+        # Every name a rule resolves at its root — the first segment of
+        # each `lookup` path, unique, in first-seen order.
+        def lookup_heads(ast)
+          heads = []
+          each_node(ast) do |node|
+            heads << node["path"].first.to_s if node["op"] == "lookup" && node["path"].is_a?(::Array)
+          end
+          heads.uniq
+        end
+
+        def each_node(node, &block)
+          case node
+          when ::Hash
+            yield node
+            node.each_value { |child| each_node(child, &block) }
+          when ::Array
+            node.each { |child| each_node(child, &block) }
+          end
+        end
+
         def emit_bool(node)
           case node
           when Evaluator::Or  then { "op" => "or", "left" => emit_bool(node.left), "right" => emit_bool(node.right) }
@@ -73,12 +138,13 @@ module Hecks
           when Evaluator::Resolve
             emit_resolver(node.expr)
           else
-            raise "unhandled evaluator node #{node.class} — no JSON rendering exists for it (lib/hecks/bluebook/expression/ast_json.rb#emit_bool)"
+            raise "unhandled evaluator node #{node.class} — no JSON rendering exists for it " \
+                  "(lib/hecks/bluebook/expression/ast_json.rb#emit_bool)"
           end
         end
 
-        def emit_comparison(op)
-          { "less_than" => op.compares_less_than, "equal" => op.compares_equal, "negated" => op.negated }
+        def emit_comparison(comparator)
+          { "less_than" => comparator.compares_less_than, "equal" => comparator.compares_equal, "negated" => comparator.negated }
         end
 
         # The JSON-target sibling of `expr_emitter.rb`'s own
@@ -99,11 +165,18 @@ module Hecks
           return { "op" => "bool", "value" => false } if node.haystack.elements.empty?
 
           equalities = node.haystack.elements.map do |element|
-            { "op" => "compare", "cmp" => emit_comparison(EQ), "left" => emit_resolver(node.needle), "right" => emit_resolver(element) }
+            { "op" => "compare", "cmp" => emit_comparison(EQ), "left" => emit_resolver(node.needle),
+"right" => emit_resolver(element) }
           end
           equalities.reduce { |left, right| { "op" => "or", "left" => left, "right" => right } }
         end
 
+        # One case arm per Resolver node type — the class header above is
+        # explicit that this dispatch must stay COMPLETE and in one place
+        # ("every node this grammar admits gets a real arm"); splitting it
+        # into several methods would hide whether the set is still
+        # exhaustive instead of making that visible at a glance.
+        # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
         def emit_resolver(node)
           case node
           when Resolver::IntegerLiteral then { "op" => "int", "value" => node.value }
@@ -111,7 +184,9 @@ module Hecks
           when Resolver::StringLiteral  then { "op" => "str", "value" => node.value }
           when Resolver::BoolLiteral    then { "op" => "bool", "value" => node.value }
           when Resolver::NilLiteral     then { "op" => "nil" }
-          when Resolver::Lookup         then { "op" => "lookup", "path" => node.path }
+          # `path` is the SAME shape `find.path` already has — segments, not
+          # a dotted string a reader would have to split by its own rule.
+          when Resolver::Lookup         then { "op" => "lookup", "path" => node.path.split(".") }
           when Resolver::Addition       then { "op" => "add", "left" => emit_resolver(node.left), "right" => emit_resolver(node.right) }
           when Resolver::SignTest
             { "op" => "sign_test", "cmp" => emit_comparison(node.operator), "receiver" => emit_resolver(node.receiver) }
@@ -128,9 +203,12 @@ module Hecks
           when Resolver::ArrayLiteral
             { "op" => "array", "elements" => node.elements.map { |element| emit_resolver(element) } }
           when Resolver::MatchesRegex
-            { "op" => "matches_regex", "receiver" => emit_resolver(node.receiver), "pattern" => node.pattern, "flags" => node.flags }
+            { "op" => "matches_regex", "receiver" => emit_resolver(node.receiver), "pattern" => node.pattern,
+"flags" => node.flags }
           when Resolver::Presence
             { "op" => "presence", "receiver" => emit_resolver(node.receiver), "negated" => node.negated }
+          when Resolver::Assignment
+            { "op" => "assignment", "receiver" => emit_resolver(node.receiver), "negated" => node.negated }
           when Resolver::Split
             { "op" => "split", "receiver" => emit_resolver(node.receiver), "separator" => node.separator }
           when Resolver::StartsWith
@@ -140,7 +218,8 @@ module Hecks
           when Resolver::First then { "op" => "first", "receiver" => emit_resolver(node.receiver) }
           when Resolver::Last  then { "op" => "last", "receiver" => emit_resolver(node.receiver) }
           else
-            raise "unhandled resolver node #{node.class} — no JSON rendering exists for it (lib/hecks/bluebook/expression/ast_json.rb#emit_resolver)"
+            raise "unhandled resolver node #{node.class} — no JSON rendering exists for it " \
+                  "(lib/hecks/bluebook/expression/ast_json.rb#emit_resolver)"
           end
         end
       end