hecks 4.0.0 → 6.0.0

data/lib/hecks/bluebook/dsl/entity_builder/scope.rb

@@ -4,10 +4,10 @@ module Hecks
       class EntityBuilder
         # What a piece is handed by whatever declares it, threaded unchanged through every nested
         # piece so siblings share the same pools: the owner's value objects and givens, the
-        # naming of identity value objects, and the chapter-wide entity-given pools.
+        # naming of identity value objects, and the bluebook-wide entity-given pools.
         Scope = Struct.new(:owner_value_objects, :owner_named_givens, :identity_name_prefix,
                            :identity_value_object_installer, :aggregate_name,
-                           :chapter_entity_named_givens, :chapter_entity_pending_givens,
+                           :bluebook_entity_named_givens, :bluebook_entity_pending_givens,
                            keyword_init: true) do
           # Builds a `Scope` with every field defaulted to empty, refusing an unknown keyword.
           #
@@ -16,7 +16,7 @@ module Hecks
           def self.from(**context)
             new(owner_value_objects: [], owner_named_givens: {}, identity_name_prefix: nil,
                 identity_value_object_installer: nil, aggregate_name: nil,
-                chapter_entity_named_givens: {}, chapter_entity_pending_givens: [], **context)
+                bluebook_entity_named_givens: {}, bluebook_entity_pending_givens: [], **context)
           end
         end
       end

data/lib/hecks/bluebook/dsl/entity_builder/sealing.rb

@@ -43,8 +43,8 @@ module Hecks
                                       identity_name_prefix:            "#{@identity_name_prefix}#{Naming.demodulise(name)}",
                                       identity_value_object_installer: @identity_value_object_installer,
                                       aggregate_name:                  @aggregate_name,
-                                      chapter_entity_named_givens:     @chapter_entity_named_givens,
-                                      chapter_entity_pending_givens:   @chapter_entity_pending_givens,
+                                      bluebook_entity_named_givens:    @bluebook_entity_named_givens,
+                                      bluebook_entity_pending_givens:  @bluebook_entity_pending_givens,
                                 &block)
           end
 

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

@@ -132,11 +132,11 @@ module Hecks
           # Threaded unchanged through every nested piece so a sibling's bare given
           # reference can read the same aggregate-wide pool `given_impl` writes to.
           @owner_named_givens = scope.owner_named_givens
-          # One level wider than `@owner_named_givens`: the chapter-wide, entity-scoped
+          # One level wider than `@owner_named_givens`: the bluebook-wide, entity-scoped
           # pool, keyed "Aggregate.Entity" so `#given_impl` can resolve across aggregates.
           @aggregate_name = scope.aggregate_name || Naming.demodulise(name)
-          @chapter_entity_named_givens   = scope.chapter_entity_named_givens
-          @chapter_entity_pending_givens = scope.chapter_entity_pending_givens
+          @bluebook_entity_named_givens   = scope.bluebook_entity_named_givens
+          @bluebook_entity_pending_givens = scope.bluebook_entity_pending_givens
         end
 
         def entity_fields

data/lib/hecks/bluebook/dsl/hecksagon_builder/{chapter_scope.rb → bluebook_scope.rb}

@@ -3,9 +3,9 @@ module Hecks
     module DSL
       class HecksagonBuilder
         # The per-thread state of the hecksagon build in progress, and the shadowing of `Hecks`'s
-        # real modules that lets the Hecks chapter spell its aggregates `Hecks::Operation`.
+        # real modules that lets the Hecks bluebook spell its aggregates `Hecks::Operation`.
         # Extended onto `HecksagonBuilder`.
-        module ChapterScope
+        module BluebookScope
           # The bind collector of the build running on this thread; thread-local, so a build
           # on another thread never sees it.
           #
@@ -17,10 +17,10 @@ module Hecks
             Thread.current.thread_variable_set(:hecks_hecksagon_collector, value)
           end
 
-          # @return [String, nil] the name of the chapter whose hecksagon is being built
+          # @return [String, nil] the name of the bluebook whose hecksagon is being built
           def building = Thread.current.thread_variable_get(:hecks_hecksagon_building)
 
-          # @param value [String, nil] the name of the chapter whose hecksagon is being built
+          # @param value [String, nil] the name of the bluebook whose hecksagon is being built
           def building=(value)
             Thread.current.thread_variable_set(:hecks_hecksagon_building, value)
           end
@@ -33,17 +33,17 @@ module Hecks
             Thread.current.thread_variable_set(:hecks_hecksagon_hidden, value)
           end
 
-          # Takes off `Hecks` each real module a chapter aggregate shares its name with, so the
-          # name reaches `ChapterConstants#const_missing`. Only the chapter named Hecks has this
+          # Takes off `Hecks` each real module a bluebook aggregate shares its name with, so the
+          # name reaches `BluebookConstants#const_missing`. Only the bluebook named Hecks has this
           # collision; a nested build of it leaves the outer build's shadows in place.
           #
-          # @param domain [String, Symbol] the chapter whose hecksagon is being built
+          # @param domain [String, Symbol] the bluebook whose hecksagon is being built
           # @return [Hash{Symbol => Object}] what was taken off, by name: the module, or the
           #   autoload path when the constant had not loaded yet
           def shadowed(domain)
             return {} unless domain.to_s == "Hecks"
 
-            chapter_aggregate_names.select { |name| Hecks.const_defined?(name, false) }.to_h do |name|
+            bluebook_aggregate_names.select { |name| Hecks.const_defined?(name, false) }.to_h do |name|
               pending = Hecks.autoload?(name)
               held    = pending ? [:autoload, pending] : [:module, Hecks.const_get(name, false)]
               Hecks.send(:remove_const, name)
@@ -52,7 +52,7 @@ module Hecks
           end
 
           # Runs the block with every module the running build shadowed back on `Hecks`, and a
-          # missing `Hecks::X` an ordinary `NameError`, then shadows them again. A chapter loaded
+          # missing `Hecks::X` an ordinary `NameError`, then shadows them again. A bluebook loaded
           # from inside the hecksagon block is ordinary code, not the hecksagon's own vocabulary.
           # A no-op when nothing is shadowed.
           #
@@ -83,10 +83,10 @@ module Hecks
             end
           end
 
-          # Runs the block with this thread's collector, chapter name and shadowed modules set for
+          # Runs the block with this thread's collector, bluebook name and shadowed modules set for
           # building `domain`'s hecksagon, restoring the outer build's state afterwards.
           #
-          # @param domain [String, Symbol] the chapter whose hecksagon is being built
+          # @param domain [String, Symbol] the bluebook whose hecksagon is being built
           # @param binds [Array] the binds the build collects into
           # @yield the build
           # @return [Object] the block's result
@@ -101,9 +101,9 @@ module Hecks
 
           private
 
-          def chapter_aggregate_names
-            chapter = Hecks.current_registry&.bluebook("Hecks")
-            chapter ? chapter.aggregates.map { |aggregate| aggregate.hecks_name.to_sym } : []
+          def bluebook_aggregate_names
+            declaration = Hecks.current_registry&.bluebook("Hecks")
+            declaration ? declaration.aggregates.map { |aggregate| aggregate.hecks_name.to_sym } : []
           end
 
           def reshadow(hidden, name)

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

@@ -1,5 +1,5 @@
 require_relative "word_gate"
-require_relative "hecksagon_builder/chapter_scope"
+require_relative "hecksagon_builder/bluebook_scope"
 module Hecks
   module Bluebook
     module DSL
@@ -9,18 +9,18 @@ module Hecks
         GRAMMAR_CONTEXT = "Hecksagon".freeze
 
         include WordGate
-        extend ChapterScope
+        extend BluebookScope
 
-        # Lets the Hecks chapter's own hecksagon spell its aggregates `Hecks::Operation`.
+        # Lets the Hecks bluebook's own hecksagon spell its aggregates `Hecks::Operation`.
         #
-        # While the chapter named Hecks builds its hecksagon, a missing constant on `Hecks` is
-        # one of that chapter's aggregates; at any other time it is the ordinary `NameError`.
+        # While the bluebook named Hecks builds its hecksagon, a missing constant on `Hecks` is
+        # one of that bluebook's aggregates; at any other time it is the ordinary `NameError`.
         #
         # A real module of the same name (`Hecks::Release`) would answer first, so
         # `HecksagonBuilder.build` takes each off `Hecks` while the block runs (see `shadowed`).
-        # `attaches` loads whole chapters inside the block; the shadow lifts around each load
+        # `attaches` loads whole bluebooks inside the block; the shadow lifts around each load
         # (see `with_real_modules`), so loaded code sees the real modules.
-        module ChapterConstants
+        module BluebookConstants
           # @param name [Symbol] the missing constant
           # @return [Bluebook::DSL::BindingProxy] a proxy for that aggregate while building
           def const_missing(name)
@@ -37,6 +37,10 @@ module Hecks
           "uses_embryonaut_bluebook" => ->(name) { "attaches #{name.to_s.inspect}, from: :vendor" }
         }.freeze
 
+        # Words older hecksagons carry that no grammar word or port defines and nothing reads. They
+        # are refused by name so the file fails at the line, not later as an unknown adapter.
+        RETIRED_WORDS = %w[capabilities concerns annotate].freeze
+
         attr_reader :binds, :subscriptions, :attachments
 
         def initialize(domain)
@@ -49,7 +53,7 @@ module Hecks
           @translates         = []
         end
 
-        # Marks this chapter as a bounded context; an attachment marks its chapter bounded too.
+        # Marks this bluebook as a bounded context; an attachment marks its bluebook bounded too.
         # Must declare at least one `translates` ACL or boot refuses.
         def bounded
           @bounded = true
@@ -65,15 +69,15 @@ module Hecks
         # @return [void]
         def driven_by(adapter) = @driving << adapter.to_s
 
-        # Attaches a chapter by name and loads it into the current registry, marked bounded.
+        # Attaches a bluebook by name and loads it into the current registry, marked bounded.
         #
-        # Without `from:` the name is a chapter the gem carries (a framework member such as
-        # Governance, or a language chapter such as Deploy) with the ports and adapters it
+        # Without `from:` the name is a bluebook the gem carries (a framework member such as
+        # Governance, or a language bluebook such as Deploy) with the ports and adapters it
         # ships. `from: :vendor` loads `vendor/embryonaut_bluebooks/<name>/bluebook` instead,
         # and is never a fallback for a misspelt gem name.
         #
-        # @param name [String, Symbol] a gem chapter's name or a vendored package's directory name
-        # @param from [Symbol, nil] `:vendor` for a vendored package, nil for a gem chapter
+        # @param name [String, Symbol] a gem bluebook's name or a vendored package's directory name
+        # @param from [Symbol, nil] `:vendor` for a vendored package, nil for a gem bluebook
         # @raise [Runtime::WiringError] if the name is unknown, or `from:` names another source
         def attaches(name, from: nil)
           unless [nil, :vendor].include?(from)
@@ -84,7 +88,7 @@ module Hecks
           from == :vendor ? attach_vendored(name) : attach_gem(name)
         end
 
-        # Declares a port at the hecksagon's root — the chapter as a whole, not one aggregate.
+        # Declares a port at the hecksagon's root — the bluebook as a whole, not one aggregate.
         def port_impl(name, &block)
           bluebook_ir = Hecks.current_registry.bluebook(@domain) or
             raise Malformed, "#{@domain} declares no such bluebook — a port needs one to belong to"
@@ -123,21 +127,21 @@ module Hecks
                         driving: @driving)
         end
 
-        # Loads a chapter the gem carries and records it as attached from the gem.
+        # Loads a bluebook the gem carries and records it as attached from the gem.
         def attach_gem(name)
-          require_relative "../../chapters"
+          require_relative "../../framework_bluebooks"
           @attachments << Attachment.new(name: name.to_s, source: :gem)
-          self.class.with_real_modules { Hecks::Chapters.attach!(name) }
+          self.class.with_real_modules { Hecks::FrameworkBluebooks.attach!(name) }
           Hecks.current_registry&.mark_bounded(name.to_s)
         end
         private :attach_gem
 
-        # Loads a vendored package and records it as attached from `vendor/`. The directory name
-        # Pascal-cases to the chapter name (`"membership"` becomes `Membership`).
+        # Loads a vendored package and records it as attached from `vendor/`, under the bluebook
+        # its bluebook declares: `"document"` attaches `Documents`.
         def attach_vendored(name)
-          @attachments << Attachment.new(name: name.to_s, source: :vendor)
-          Hecks::EmbryonautBluebook.load!(name)
-          Hecks.current_registry&.mark_bounded(Hecks::Naming.pascal(name.to_s))
+          declaration = Hecks::EmbryonautBluebook.load!(name)
+          @attachments << Attachment.new(name: name.to_s, source: :vendor, declaration: declaration)
+          Hecks.current_registry&.mark_bounded(declaration)
         end
         private :attach_vendored
 
@@ -158,16 +162,18 @@ module Hecks
           self
         end
 
-        # Raises for a word 3.4.0 removed, naming the spelling that replaces it.
+        # Raises for a word 3.4.0 removed, naming the spelling that replaces it, and for a retired
+        # word that has no replacement.
         #
         # @param verb [Symbol] the word the hecksagon block called
         # @param name [Object, nil] its first argument, echoed into the replacement
-        # @raise [Malformed] when the word is one of `REMOVED_WORDS`
+        # @raise [Malformed] when the word is one of `REMOVED_WORDS` or `RETIRED_WORDS`
         def refuse_removed_word(verb, name)
           instead = REMOVED_WORDS[verb.to_s]
-          return unless instead
+          raise Malformed, "`#{verb}` was removed in 3.4.0; use `#{instead.call(name)}`" if instead
+          return unless RETIRED_WORDS.include?(verb.to_s)
 
-          raise Malformed, "`#{verb}` was removed in 3.4.0; use `#{instead.call(name)}`"
+          raise Malformed, "`#{verb}` is not a hecksagon word and nothing reads it; delete the line"
         end
         private :refuse_removed_word
 
@@ -188,4 +194,4 @@ module Hecks
   end
 end
 
-Hecks.singleton_class.prepend(Hecks::Bluebook::DSL::HecksagonBuilder::ChapterConstants)
+Hecks.singleton_class.prepend(Hecks::Bluebook::DSL::HecksagonBuilder::BluebookConstants)

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

@@ -4,6 +4,9 @@ module Hecks
       # `identified_by`, shared by AggregateBuilder and EntityBuilder (ADR 0025).
       # The includer must include AttributeCollector and define a private `identity_pool`.
       module IdentityDeclaration
+        # A name that starts with a capital letter: a value-object type, not an attribute name.
+        CAPITALISED = /\A[A-Z]/
+
         # Records which `identified_by` form a builder declared; resolution waits for build time.
         #
         #   identified_by AccountNumber, as: :number # one identity concept
@@ -41,7 +44,7 @@ module Hecks
           end
         end
 
-        def identity_type?(target) = target.to_s.match?(/\A[A-Z]/)
+        def identity_type?(target) = target.to_s.match?(CAPITALISED)
 
         def refuse_second_identity!
           # Transitional: a one-symbol declaration may still be replaced by a later one.
@@ -110,7 +113,8 @@ module Hecks
 
           raise Malformed, "#{@name}.identified_by names no field" unless path
 
-          paths = Ports::Extraction.canonical(path).to_s.split.reject(&:empty?)
+          canonical = Ports::Extraction.canonical(path).to_s
+          paths = canonical.split.reject(&:empty?)
           raise Malformed, "#{@name}.identified_by names no field" if paths.empty?
 
           @identity_paths = paths

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

@@ -6,6 +6,9 @@ module Hecks
       class LifecycleBuilder
         GRAMMAR_CONTEXT = "Lifecycle".freeze
 
+        # A lowercase word: a letter, then letters, digits and underscores (`holds_seat`).
+        LOWERCASE_WORD = /\A[a-z][a-z0-9_]*\z/
+
         include WordGate
 
         # @param field [Symbol, String] the attribute the state machine lives on, such as `:status`
@@ -29,7 +32,7 @@ module Hecks
         #   declared twice, no states, or a state named twice in one mark
         def mark_impl(name, *states)
           mark = name.to_s
-          unless mark.match?(/\A[a-z][a-z0-9_]*\z/)
+          unless mark.match?(LOWERCASE_WORD)
             raise Malformed, "lifecycle :#{@field} mark #{name.inspect} is not a lowercase word (such as :holds_seat)"
           end
           raise Malformed, "lifecycle :#{@field} declares mark :#{mark} twice" if @marks.key?(mark)

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

@@ -74,8 +74,8 @@ module Hecks
         # Assembles the declared parameters and filtering into a `Query`.
         #
         # @return [Bluebook::Query] the built query
-        # @raise [Bluebook::DSL::Malformed] if the body declares `cursor`, which no interpreter
-        #   implements
+        # @raise [Bluebook::DSL::Malformed] if `cursor` is declared without a `limit` and a matching
+        #   order, or beside an `offset`
         def build
           seal_cursor
           refuse_undeclared_needs!
@@ -89,7 +89,8 @@ module Hecks
         #   entity's own attributes, matched against the block's own parameter names
         # @yield the query body, evaluated with the builder as `self`; may be omitted
         # @return [Bluebook::Query] the built query
-        # @raise [Bluebook::DSL::Malformed] if the body declares `cursor`, a duplicate attribute,
+        # @raise [Bluebook::DSL::Malformed] if the body declares an unsound `cursor`, a duplicate
+        #   attribute,
         #   or a filtering clause the query language refuses
         def self.build(name, owner_attributes: [], &block)
           builder = new(name)
@@ -130,15 +131,20 @@ module Hecks
           end
         end
 
-        # `cursor` parses and round-trips but no interpreter applies it; refuse it so an author
-        # does not believe cursor pagination happens.
+        # `cursor :field` pages the query by its order field and identity (ADR 0130), so it needs
+        # the page size (`limit`), an order it can key on, and no `offset` beside it.
         def seal_cursor
           return unless @cursor
 
-          raise Malformed,
-                "#{@name} declares cursor, but no interpreter implements cursor " \
-                "pagination — use limit/offset instead"
+          refuse_cursor!("a cursor pages by a page size — add `limit N`") unless @limit
+          refuse_cursor!("a cursor and an offset both position the page — drop `offset`") if @offset
+          return if @cursor.value.to_s == (@order_by ? @order_by.field.to_s : "id")
+
+          refuse_cursor!("the cursor must name the field the query orders by " \
+                         "(`cursor :#{@order_by ? @order_by.field : "id"}`)")
         end
+
+        def refuse_cursor!(fix) = raise(Malformed, "#{@name} declares cursor, but #{fix}")
       end
     end
   end

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

@@ -69,8 +69,8 @@ module Hecks
           end
 
           # Every reduction (`Behaviour::ReadModel::REDUCTION_FIELDS`) needs exactly one
-          # many-side head, cannot be declared alongside another, and cannot combine with
-          # `group_by`: a read model reports one shape.
+          # many-side head and cannot be declared alongside another: a read model reports one
+          # shape. With `group_by` it reduces each group's rows instead (ADR 0126).
           def seal_aggregation
             declared = Behaviour::ReadModel::REDUCTION_FIELDS
                        .select { |ivar, _| instance_variable_get(:"@#{ivar}") }.values
@@ -87,11 +87,6 @@ module Hecks
           end
 
           def refuse_mixed_shapes!(declared)
-            if @group_by&.any?
-              raise Malformed,
-                    "#{@name} declares #{declared.join("/")} together with group_by — a read " \
-                    "model reports one shape; choose one"
-            end
             return unless declared.size > 1
 
             joiner = declared.size == 2 ? "both #{declared.join(" and ")}" : declared.join(", ")
@@ -100,14 +95,14 @@ module Hecks
 
           def many_side_count = Array(@aggregate_heads).count { |head| head[:many] }
 
-          # `cursor` is parsed but no interpreter applies it, so it is refused rather than
-          # letting an author believe cursor pagination happens.
+          # A cursor pages a query (ADR 0130); a read model's many-side head does not page yet, so
+          # is refused rather than letting an author believe it does.
           def seal_cursor
             return unless @cursor
 
             raise Malformed,
-                  "#{@name} declares cursor, but no interpreter implements cursor " \
-                  "pagination — use limit/offset instead"
+                  "#{@name} declares cursor, but a read model does not page by cursor yet — " \
+                  "cursor pages a query; use limit/offset here"
           end
         end
       end

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

@@ -154,8 +154,7 @@ module Hecks
         # @raise [Bluebook::DSL::Malformed] if neither `reference_to` nor any `include` is
         #   declared, if `where`/`order_by`/`limit`/`offset`/`group_by` or a reduction name an
         #   `on:` that isn't a many-side include or are left untargeted with more than one
-        #   many-side head, if more than one reduction is declared or one is combined with
-        #   `group_by`, or if `cursor` is declared
+        #   many-side head, if more than one reduction is declared, or if `cursor` is declared
         def build
           if !@reference_target && Array(@includes).empty?
             raise Malformed,

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

@@ -55,7 +55,8 @@ module Hecks
         end
 
         def refuse_unadmitted_word!(keywords, context, word)
-          legal = keywords.select { |row| row[:context] == context }.map { |row| row[:word] }.uniq.sort
+          words = keywords.select { |row| row[:context] == context }.map { |row| row[:word] }
+          legal = words.uniq.sort
           raise Malformed,
                 "'#{word}' is not a word #{context} admits — legal words here: #{legal.join(", ")}"
         end

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

@@ -64,7 +64,7 @@ module Hecks
           @latest = required(value, "latest version")
         end
 
-        # A chapter's own `persisted_by("Adapter") { database ... }` still wins for that adapter.
+        # A bluebook's own `persisted_by("Adapter") { database ... }` still wins for that adapter.
         def default_database_impl(value)
           @default_database = required(value, "default database")
         end
@@ -112,7 +112,7 @@ module Hecks
         # Wraps `instance_eval` in `ConstShim`'s resolver: without it, an aggregate-qualified
         # verb call raises `NameError`, since the bare constant has nothing to resolve to.
         # A bare name resolves to a namespace whose `::` reaches the proxy; a qualified path
-        # (`Pizzas::Order`, handed over by an installed facade chapter's `const_missing`)
+        # (`Pizzas::Order`, handed over by an installed facade bluebook's `const_missing`)
         # is already the aggregate, so it resolves to the proxy itself.
         #
         # @param domain [String] the domain the world belongs to

data/lib/hecks/bluebook/dsl.rb

@@ -15,9 +15,9 @@ end
 require_relative "../construct"
 require_relative "../query_specification"
 # The model the builders construct — `bluebook.rb` requires the whole
-# set; this names the one file that declares the chapter class itself,
+# set; this names the one file that declares the bluebook class itself,
 # which every builder returns into.
-require_relative "chapter"
+require_relative "declaration"
 
 require_relative "dsl/malformed"
 require_relative "dsl/const_shim"
@@ -42,4 +42,5 @@ require_relative "dsl/hecksagon_builder"
 require_relative "dsl/port_builder"
 require_relative "dsl/adapter_builder"
 require_relative "dsl/world_builder"
+require_relative "dsl/context_map_builder"
 require_relative "dsl/translation_builder"

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

@@ -77,6 +77,10 @@ module Hecks
               { "op" => "find", "receiver" => AstJson.emit_resolver(node.receiver), "param" => node.param.to_s,
                 "predicate" => AstJson.emit_bool(node.predicate), "path" => node.path.map(&:to_s) }
             },
+            Resolver::Sum            => lambda { |node|
+              { "op" => "sum", "receiver" => AstJson.emit_resolver(node.receiver), "param" => node.param.to_s,
+                "predicate" => AstJson.emit_bool(node.predicate) }
+            },
             Resolver::ArrayLiteral   => lambda { |node|
               { "op" => "array", "elements" => node.elements.map { |element| AstJson.emit_resolver(element) } }
             },

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

@@ -20,7 +20,7 @@ module Hecks
           or and not compare include
           int float str bool nil array lookup
           add sub mul div modulo sign_test empty size to_s
-          block_predicate find first last
+          block_predicate find sum first last
           matches_regex presence assignment split strip starts_with ends_with
         ].freeze
 
@@ -137,9 +137,11 @@ module Hecks
         # @param node [Evaluator::Include] an `include` over a literal-array haystack
         # @return [Hash] an or of equalities over the elements, or `false` for none
         def emit_literal_include(node)
-          return { "op" => "bool", "value" => false } if node.haystack.elements.empty?
+          haystack = node.haystack
+          elements = haystack.elements
+          return { "op" => "bool", "value" => false } if elements.empty?
 
-          equalities = node.haystack.elements.map { |element| emit_equality(node.needle, element) }
+          equalities = elements.map { |element| emit_equality(node.needle, element) }
           equalities.reduce { |left, right| { "op" => "or", "left" => left, "right" => right } }
         end
 

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

@@ -0,0 +1,41 @@
+module Hecks
+  module Bluebook
+    module Expression
+      module AstReader
+        # Reads the nodes that take a block (`all?`/`any?`/`none?`, `find`, `sum`) back from their
+        # `"op"`-tagged JSON.
+        module Blocks
+          module_function
+
+          # @param json [Hash] a resolver node
+          # @return [Object, nil] the block-taking node it spells, or `nil` for any other op
+          def read(json)
+            case json["op"]
+            when "block_predicate" then block_predicate(json)
+            when "find" then find(json)
+            when "sum" then sum(json)
+            end
+          end
+
+          # @return [Resolver::BlockPredicate] the `all?`, `any?` or `none?` node
+          def block_predicate(json)
+            Resolver::BlockPredicate.new(mode: json["mode"].to_sym, receiver: AstReader.receiver(json), param: json["param"],
+                                         predicate: AstReader.read_bool(json["predicate"]))
+          end
+
+          # @return [Resolver::Find] the `find` node, with the path it projects through
+          def find(json)
+            Resolver::Find.new(receiver: AstReader.receiver(json), param: json["param"],
+                               predicate: AstReader.read_bool(json["predicate"]), path: json["path"])
+          end
+
+          # @return [Resolver::Sum] the `sum` node
+          def sum(json)
+            Resolver::Sum.new(receiver: AstReader.receiver(json), param: json["param"],
+                              predicate: AstReader.read_bool(json["predicate"]))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -143,16 +143,7 @@ module Hecks
 
         # @param json [Hash] a resolver node
         # @return [Object, nil] the block-taking node it spells, or `nil` for any other op
-        def read_block(json)
-          case json["op"]
-          when "block_predicate"
-            Resolver::BlockPredicate.new(mode: json["mode"].to_sym, receiver: receiver(json), param: json["param"],
-                                         predicate: read_bool(json["predicate"]))
-          when "find"
-            Resolver::Find.new(receiver: receiver(json), param: json["param"],
-                               predicate: read_bool(json["predicate"]), path: json["path"])
-          end
-        end
+        def read_block(json) = Blocks.read(json)
 
         # @return [Object] the resolver node under `json`'s `"receiver"`
         def receiver(json) = read_resolver(json["receiver"])
@@ -164,3 +155,4 @@ module Hecks
     end
   end
 end
+require_relative "ast_reader/blocks"

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

@@ -11,10 +11,15 @@ module Hecks
 
         STRATEGIES = Hecks::Vocabulary.fetch("NormalisationStrategy")
 
-        # Normalisation rules projected from the grammar chapter by hecks project_expression_tables.
-        RULES = JSON.parse(
+        # The normalisation rows projected from the grammar bluebook by hecks
+        # project_expression_tables, as plain Hashes.
+        NORMALISATION_ROWS = JSON.parse(
           File.read(File.join(__dir__, "projection.json")), symbolize_names: true
-        ).fetch(:normalisations).map { |row| Rule.new(**row) }.freeze
+        ).fetch(:normalisations)
+
+        # Normalisation rules projected from the grammar bluebook by hecks
+        # project_expression_tables.
+        RULES = NORMALISATION_ROWS.map { |row| Rule.new(**row) }.freeze
 
         module_function
 
@@ -38,7 +43,7 @@ module Hecks
 
         def step(text, rule)
           case rule.strategy
-          when "collapse_whitespace" then map_outside_strings(text) { |segment| segment.gsub(/\s+/, " ") }
+          when "collapse_whitespace" then map_outside_strings(text) { |segment| segment.gsub(Text::WHITESPACE, " ") }
           when "replace"             then replace(text, rule)
           when "scale_call"          then scale_call(text, rule)
           else

data/lib/hecks/bluebook/expression/evaluator/parser.rb

@@ -8,6 +8,9 @@ module Hecks
         # Turns a canonical predicate string into an `Or`/`And`/`Not`/`Include`/`Compare`/`Resolve`
         # AST, trying the loosest-binding form first.
         module Parser
+          # A leading `!` and the whole remainder after it, captured.
+          NEGATION = /\A!(.+)\z/
+
           module_function
 
           # Parses `expr`'s boolean/comparison grammar into an AST; leaves go to `Resolver.parse`.
@@ -35,7 +38,7 @@ module Hecks
           #
           # @return [Not, nil] the negation of what follows a leading `!`, else `nil`
           def parse_not(expr)
-            negated = expr.match(/\A!(.+)\z/)
+            negated = expr.match(NEGATION)
             Not.new(node: parse(negated[1])) if negated
           end