hecks 5.0.0 → 7.0.0

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

@@ -17,6 +17,15 @@ module Hecks
           @handlers = []
         end
 
+        # Records the key that ties one instance's events together. A dotted path or symbol is
+        # kept as written; a bare aggregate name (`correlates_by Message`) is kept as its bare
+        # name, which `BluebookBuilder` resolves to `"Message.<identity>"` once every aggregate
+        # is known.
+        #
+        # @param key [Symbol, String, Module] the dotted path, or a bare aggregate name
+        # @return [void]
+        def correlates_by_impl(key) = @correlates_by = key
+
         # Records the event that begins a fresh instance of this process manager.
         #
         # `starts_on Transfer::TransferRequested`: a bare constant, stored as the bare event
@@ -35,9 +44,14 @@ module Hecks
         # @param event_ref [Symbol, String, Module] the event, as a bare constant (a
         #   `ScopedConstant` module `ConstShim` resolves) or quoted text
         # @return [void]
-        def ends_on_impl(event_ref)
-          @ends_on = Naming.event_name_ref(event_ref)
-        end
+        def ends_on_impl(event_ref) = (@endings ||= []) << Naming.event_name_ref(event_ref)
+
+        # Records the command that resumes one stage, written `stage=command`, as the stage
+        # map a resume reads. The runtime does not read it yet.
+        #
+        # @param entry [String] one `stage=command` pair, for example `"gated=GateRun.Gate"`
+        # @return [void]
+        def resumes_impl(entry) = (@resumes ||= []) << entry.to_s
 
         # Records one leg of the state machine: the event that takes it, the state(s) it
         # applies from, and the dispatches (with optional compensations) it fires.
@@ -81,7 +95,8 @@ module Hecks
             name:          @name,
             correlates_by: @correlates_by,
             starts_on:     @starts_on,
-            ends_on:       @ends_on,
+            ends_on:       @endings&.first,
+            endings: @endings || [], resumes: @resumes || [],
             states:        derived_states,
             handlers:      @handlers
           )
@@ -148,19 +163,14 @@ module Hecks
           refuse_ambiguous_legs!
         end
 
+        # A bare name is not checked here: it may name an aggregate, which only the bluebook
+        # can see. `BluebookBuilder` resolves it to `"<Aggregate>.<identity>"`, or refuses it
+        # with `bare_correlation_message`. A dotted path is a scalar by its spelling.
         def refuse_bad_correlation!
-          unless @correlates_by
-            raise InvalidProcessManager, "#{@name} declares no correlates_by — " \
-                                         "nothing would tie its events to one instance"
-          end
-
-          # Names a scalar (`:"end_to_end.value"`), never a whole field or value object.
-          # A syntactic check: the dotted spelling leaves no question about the key's type.
-          return if @correlates_by.to_s.include?(".")
+          return if @correlates_by
 
-          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"
+          raise InvalidProcessManager, "#{@name} declares no correlates_by — " \
+                                       "nothing would tie its events to one instance"
         end
 
         # A leg is selected by (event, current state), so two legs on the same pair would

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/translation_builder.rb

@@ -121,6 +121,20 @@ module Hecks
         # `method_missing`/`respond_to_missing?` (via the included `WordGate`) give a
         # table-driven refusal naming the legal words, rather than a hand-typed list.
 
+        # ADR 0166: writes rows into `into` from this aggregate's rows, keyed by `keyed_by`.
+        #
+        # @param into [String, Symbol] the aggregate that receives the rows
+        # @param keyed_by [Symbol] the field both aggregates carry, which the target identifies by
+        # @param fields [Array<Symbol>] the fields copied into the target
+        # @raise [Bluebook::DSL::Malformed] if any of the three is missing or empty
+        def split_impl(into: nil, keyed_by: nil, fields: nil)
+          raise Malformed, "a split needs a target aggregate (into:)" if into.to_s.empty?
+          raise Malformed, "a split needs a key field (keyed_by:)" if keyed_by.to_s.empty?
+          raise Malformed, "a split needs at least one field (fields:)" if Array(fields).empty?
+
+          @splits << TranslationSplit.new(into.to_s, keyed_by.to_sym, Array(fields).map(&:to_sym))
+        end
+
         # Assembles the declared rules into a `TranslationAggregate`.
         #
         # @return [Bluebook::TranslationAggregate] the built per-aggregate translation
@@ -128,7 +142,7 @@ module Hecks
           TranslationAggregate.new(
             name: @name, was: @was, renames: @renames, moves: @moves, converts: @converts,
             drops: @drops, retypes: @retypes, derives: @derives, rekeys: @rekeys,
-            backfills: @backfills
+            backfills: @backfills, splits: @splits
           )
         end
 
@@ -142,6 +156,7 @@ module Hecks
           @retypes   = []
           @derives   = []
           @rekeys    = []
+          @splits    = []
           @backfills = []
         end
 

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
@@ -71,7 +72,7 @@ module Hecks
 
           refuse_unadmitted_word!(keywords, context, word) if admitted.empty?
 
-          dispatched = GenericDispatch.try(self, context, word.to_s, args, kwargs, block, rows)
+          dispatched = GenericDispatch.try(self, context, word.to_s, GenericDispatch::Invocation.new(args, kwargs, block), rows)
           return dispatched unless dispatched.equal?(GenericDispatch::NOT_HANDLED)
 
           raise Malformed,

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"
@@ -25,6 +25,7 @@ require_relative "dsl/attribute_collector"
 require_relative "dsl/identity_declaration"
 require_relative "dsl/rule_reference"
 require_relative "dsl/word_gate"
+require_relative "dsl/kinds"
 require_relative "dsl/value_object_builder"
 require_relative "dsl/command_builder"
 require_relative "dsl/lifecycle_builder"
@@ -42,4 +43,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
 

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

@@ -1,6 +1,7 @@
 require "json"
 require_relative "../../vocabulary"
 require_relative "evaluator/parser"
+require_relative "../../switches"
 
 module Hecks
   module Bluebook
@@ -11,16 +12,18 @@ module Hecks
         Operator = Struct.new(:symbol, :compares_less_than, :compares_equal, :negated, keyword_init: true)
 
         # Six comparison operators reduced to two primitives (less_than, equal).
-        # Read from the checked-in projection because the evaluator runs while the chapter boots.
+        # Read from the checked-in projection because the evaluator runs while the bluebook boots.
         # Freshness: spec/operators_export_spec.rb; conformance: spec/operator_conformance_spec.rb.
         PROJECTION = JSON.parse(
           File.read(File.join(__dir__, "projection.json")), symbolize_names: true
         ).freeze
 
-        OPERATORS = PROJECTION.fetch(:operators)
-                              .select { |row| row[:category] == "comparison" }
-                              .map { |row| Operator.new(**row.slice(:symbol, :compares_less_than, :compares_equal, :negated)) }
-                              .freeze
+        # The projection's comparison-operator rows, as plain Hashes.
+        COMPARISON_ROWS = PROJECTION.fetch(:operators).select { |row| row[:category] == "comparison" }
+
+        OPERATORS = COMPARISON_ROWS
+                    .map { |row| Operator.new(**row.slice(:symbol, :compares_less_than, :compares_equal, :negated)) }
+                    .freeze
 
         COMPARISONS = OPERATORS.map(&:symbol).freeze
 
@@ -29,7 +32,10 @@ module Hecks
         Or      = Struct.new(:left, :right, keyword_init: true)
         And     = Struct.new(:left, :right, keyword_init: true)
         Not     = Struct.new(:node, keyword_init: true)
-        Compare = Struct.new(:operator, :left, :right, keyword_init: true)
+        Compare = Struct.new(:operator, :left, :right, keyword_init: true) do
+          # @return [String] the comparison's operator as written, such as `">="`
+          def operator_symbol = operator.symbol
+        end
         Include = Struct.new(:haystack, :needle, keyword_init: true)
         Resolve = Struct.new(:expr, keyword_init: true)
 
@@ -58,7 +64,7 @@ module Hecks
         end
 
         # Evaluates a Given/Invariant by walking its structured `ast`, falling back to
-        # parsing `canonical` when the rule has none. HECKS_EVAL=string forces the text path.
+        # parsing `canonical` when the rule has none.
         #
         # @param rule [Bluebook::Given, Bluebook::Invariant] the rule to evaluate
         # @param state [Hash{Symbol => Object}] stored attribute values a `Resolve`/`Compare` leaf
@@ -69,8 +75,6 @@ module Hecks
         # @raise [EvaluationError] if `rule` resolves an unknown attribute/argument, or
         #   misapplies an operation
         def call_rule(rule, state, attrs = {})
-          return call(rule.canonical, state, attrs) if ENV["HECKS_EVAL"] == "string"
-
           interpret(ast_cache[rule.canonical] ||= nodes_for(rule), state, attrs)
         end
 

data/lib/hecks/bluebook/expression/projection.json

@@ -245,6 +245,12 @@
       "category": "arithmetic",
       "precedence": 7,
       "arity": 2
+    },
+    {
+      "symbol": ".sum",
+      "category": "enumeration",
+      "precedence": 10,
+      "arity": 2
     }
   ],
   "normalisations": [

data/lib/hecks/bluebook/expression/resolver/block_predicates.rb

@@ -22,10 +22,16 @@ module Hecks
         # Shares `param`/`predicate` with `BlockPredicate` so `interpret_with_element` serves both.
         Find = Struct.new(:receiver, :param, :predicate, :path, keyword_init: true)
 
+        # `receiver.sum { |x| EXPRESSION }`: the total of a number worked out for each element,
+        # as `items.sum { |i| i.quantity * i.price }`. Shares `param`/`predicate` with `Find`,
+        # though the block holds a number, not a test; an empty list totals 0.
+        Sum = Struct.new(:receiver, :param, :predicate, keyword_init: true)
+
         module_function
 
-        # Every suffix that opens a `{ |x| ... }` block; `.find` builds a `Find`, not a mode.
-        BLOCK_OPENER_SUFFIXES = (BLOCK_PREDICATE_MODES.keys + ["find"]).freeze
+        # Every suffix that opens a `{ |x| ... }` block; `.find` builds a `Find` and `.sum` a `Sum`,
+        # not a mode.
+        BLOCK_OPENER_SUFFIXES = (BLOCK_PREDICATE_MODES.keys + %w[find sum]).freeze
 
         # Receiver text, suffix and block parameter of an opener, up to the first body character.
         BLOCK_OPENER_PATTERN =
@@ -52,10 +58,21 @@ module Hecks
           predicate = Evaluator.parse(expr[header.end(0)...body_end].strip)
           rest = expr[(body_end + 1)..].strip
           return find_node(header, predicate, rest) if header[2] == "find"
+          return sum_node(header, predicate, rest) if header[2] == "sum"
 
           block_predicate_node(header, predicate, rest)
         end
 
+        # @param header [MatchData] the opener match: receiver text, suffix, block parameter
+        # @param predicate [Object] the parsed block body, a number rather than a test
+        # @param rest [String] the text after the closing brace
+        # @return [Sum, nil] the node, or nil unless the block ends `expr`
+        def sum_node(header, predicate, rest)
+          return nil unless rest.empty?
+
+          Sum.new(receiver: parse(header[1]), param: header[3], predicate: predicate)
+        end
+
         # @param header [MatchData] the opener match: receiver text, suffix, block parameter
         # @param predicate [Object] the parsed block body
         # @param rest [String] the text after the closing brace
@@ -112,6 +129,37 @@ module Hecks
           Evaluator.interpret(node.predicate, state, attrs.merge(node.param.to_sym => element))
         end
 
+        # `.sum { |x| EXPRESSION }` — the block's number for every element, added up with the same
+        # 64-bit overflow check an addition has. An empty list is 0.
+        #
+        # @param node [Sum] the parsed `.sum` node
+        # @param collection [Object] the interpreted receiver, expected to be an Array
+        # @param state [Hash{Symbol => Object}] the record's own current state
+        # @param attrs [Hash{Symbol => Object}] the command's own bound arguments
+        # @return [Integer, Float] the total
+        # @raise [EvaluationError] if `collection` is not an Array, or a term is not a number
+        def summed_of(node, collection, state, attrs)
+          raise EvaluationError, "sum expects a list, got #{describe(collection)}" unless collection.is_a?(Array)
+
+          collection.reduce(0) { |total, element| add(total, term_of(node, element, state, attrs)) }
+        end
+
+        # What `node`'s block works out for `element`: the value of a plain expression, or, for a
+        # block that is a test, its true or false, which the addition then refuses.
+        #
+        # @param node [Sum] the parsed `.sum` node
+        # @param element [Object] the collection element to bind
+        # @param state [Hash{Symbol => Object}] the record's current state
+        # @param attrs [Hash{Symbol => Object}] the command's bound arguments
+        # @return [Object] the block's value for `element`
+        def term_of(node, element, state, attrs)
+          bound = attrs.merge(node.param.to_sym => element)
+          body = node.predicate
+          return unwrap_scalar(interpret(body.expr, state, bound)) if body.is_a?(Evaluator::Resolve)
+
+          Evaluator.interpret(body, state, bound)
+        end
+
         # `.find { |x| PREDICATE }` — the first element the predicate accepts, then `node.path`
         # walked through it. A miss yields nil rather than raising: no match is a normal outcome.
         #

data/lib/hecks/bluebook/expression/resolver/lookups.rb

@@ -54,7 +54,8 @@ module Hecks
         end
 
         def sole_field_of(value)
-          sole = value.value_object.sole_attribute
+          definition = value.value_object
+          sole = definition.sole_attribute
           sole ? value[sole.name] : value
         end
 

data/lib/hecks/bluebook/expression/resolver/operations.rb

@@ -28,6 +28,7 @@ module Hecks
           Last           => ->(_node, value, _state, _attrs) { Resolver.last_of(value) },
           First          => ->(_node, value, _state, _attrs) { Resolver.first_of(value) },
           Find           => ->(node, value, state, attrs) { Resolver.found_of(node, value, state, attrs) },
+          Sum            => ->(node, value, state, attrs) { Resolver.summed_of(node, value, state, attrs) },
           StartsWith     => ->(node, value, _state, _attrs) { Resolver.starts_with?(value, node.substring) },
           EndsWith       => ->(node, value, _state, _attrs) { Resolver.ends_with?(value, node.substring) },
           BlockPredicate => ->(node, value, state, attrs) { Resolver.evaluate_block_predicate(node, value, state, attrs) }