hecks 1.0.2 → 1.1.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
@@ -107,8 +113,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)

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

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

@@ -0,0 +1,107 @@
+require_relative "evaluator"
+require_relative "resolver"
+
+module Hecks
+  module Bluebook
+    module Expression
+      # THE INVERSE OF `AstJson` — reads the `"op"`-tagged JSON a rule row
+      # carries as `ast` back into the SAME `Evaluator`/`Resolver` node
+      # Structs `Evaluator.parse` builds from `canonical`. This is how the
+      # runtime evaluates a rule without re-parsing its text: the one
+      # parse happened at DSL-build time, behind `AstJson`; dispatch walks
+      # the structured form (`Evaluator.call_rule`), and `canonical` stays
+      # what it always displayed as — text for humans and refusal wording.
+      #
+      # Written as the obvious mirror of `ast_json.rb`'s two walkers, arm
+      # for arm, so a new op there is a new arm here and
+      # spec/expression_ast_spec.rb's roster contract fails until it
+      # lands. Promoted from spec/support once the runtime switched —
+      # the spec proved the round trip first, then the runtime adopted it.
+      #
+      # One deliberate asymmetry, inherited: `AstJson` rewrites a
+      # LITERAL-array `.include?` into an OR of equalities (see
+      # `emit_include`), so reading never produces an `Include` over an
+      # `ArrayLiteral`. Evaluation is unchanged by that rewrite, which is
+      # exactly what the equivalence spec pins.
+      module AstReader
+        module_function
+
+        def read_predicate(json) = read_bool(json)
+
+        def read_bool(json)
+          case json.fetch("op")
+          when "or"      then Evaluator::Or.new(left: read_bool(json["left"]), right: read_bool(json["right"]))
+          when "and"     then Evaluator::And.new(left: read_bool(json["left"]), right: read_bool(json["right"]))
+          when "not"     then Evaluator::Not.new(node: read_bool(json["expr"]))
+          when "compare"
+            Evaluator::Compare.new(operator: operator(json["cmp"]),
+                                   left: read_resolver(json["left"]), right: read_resolver(json["right"]))
+          when "include"
+            Evaluator::Include.new(haystack: read_resolver(json["haystack"]), needle: read_resolver(json["needle"]))
+          else Evaluator::Resolve.new(expr: read_resolver(json))
+          end
+        end
+
+        # The comparator algebra travels as its three-flag triple; the
+        # `Operator` carrying that exact triple is the one `parse` would
+        # have chosen, because the roster (`expression/projection.json`)
+        # holds one symbol per triple.
+        def operator(cmp)
+          Evaluator::OPERATORS.find do |op|
+            op.compares_less_than == cmp.fetch("less_than") &&
+              op.compares_equal == cmp.fetch("equal") &&
+              op.negated == cmp.fetch("negated")
+          end or raise "no comparison operator has the triple #{cmp.inspect}"
+        end
+
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity -- one arm
+        # per AstJson op is the point; splitting the case would hide the roster.
+        def read_resolver(json)
+          recv = -> { read_resolver(json["receiver"]) }
+          case json.fetch("op")
+          when "int"   then Resolver::IntegerLiteral.new(value: json["value"])
+          when "float" then Resolver::FloatLiteral.new(value: json["value"])
+          when "str"   then Resolver::StringLiteral.new(value: json["value"])
+          when "bool"  then Resolver::BoolLiteral.new(value: json["value"])
+          when "nil"   then Resolver::NilLiteral.new
+          when "array" then Resolver::ArrayLiteral.new(elements: json["elements"].map { |e| read_resolver(e) })
+          when "lookup" then Resolver::Lookup.new(path: json["path"].join("."))
+          when "add"    then Resolver::Addition.new(left: read_resolver(json["left"]), right: read_resolver(json["right"]))
+          when "sign_test"
+            op = operator(json["cmp"])
+            Resolver::SignTest.new(operator: op, test: sign_test_name(op), receiver: recv.call)
+          when "empty"  then Resolver::Empty.new(receiver: recv.call)
+          when "to_s"   then Resolver::ToS.new(receiver: recv.call)
+          when "modulo" then Resolver::Modulo.new(receiver: recv.call, divisor: read_resolver(json["divisor"]))
+          when "size"   then Resolver::Size.new(receiver: recv.call)
+          when "first"  then Resolver::First.new(receiver: recv.call)
+          when "last"   then Resolver::Last.new(receiver: recv.call)
+          when "block_predicate"
+            Resolver::BlockPredicate.new(mode: json["mode"].to_sym, receiver: recv.call, param: json["param"],
+                                         predicate: read_bool(json["predicate"]))
+          when "find"
+            Resolver::Find.new(receiver: recv.call, param: json["param"],
+                               predicate: read_bool(json["predicate"]), path: json["path"])
+          when "matches_regex" then Resolver::MatchesRegex.new(receiver: recv.call, pattern: json["pattern"],
+                                                               flags: json["flags"])
+          when "presence"      then Resolver::Presence.new(receiver: recv.call, negated: json["negated"])
+          when "assignment"    then Resolver::Assignment.new(receiver: recv.call, negated: json["negated"])
+          when "split"         then Resolver::Split.new(receiver: recv.call, separator: json["separator"])
+          when "starts_with"   then Resolver::StartsWith.new(receiver: recv.call, substring: json["substring"])
+          when "ends_with"     then Resolver::EndsWith.new(receiver: recv.call, substring: json["substring"])
+          else raise "no reader handles op #{json['op'].inspect} — add an arm before AstJson can emit it"
+          end
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
+
+        # `SignTest#test` is only wording (the refusal names it); the
+        # triple is what evaluates. Recover the spelling from the
+        # vocabulary so a rebuilt node refuses with the same message the
+        # parsed one would.
+        def sign_test_name(operator)
+          Resolver::SIGN_TEST_OPERATORS.key(operator.symbol) || operator.symbol
+        end
+      end
+    end
+  end
+end

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

@@ -4,6 +4,13 @@ require_relative "../../vocabulary"
 module Hecks
   module Bluebook
     module Expression
+      # Rewrites a predicate's SOURCE TEXT into one canonical spelling
+      # before it's ever parsed or hashed — collapsing whitespace and
+      # folding admitted synonyms (e.g. `.length` → `.size`) via the
+      # `RULES` table projected from the grammar chapter, so two byte-
+      # different but equivalent predicates compare and cache identically.
+      # Never touches text inside quoted string literals
+      # (`map_outside_strings`).
       module CanonicalForm
         Rule = Struct.new(:strategy, :source_token, :replacement, :boundary, :position, keyword_init: true)