hecks 1.0.2 → 1.2.0

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)
 

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

@@ -4,6 +4,13 @@ require_relative "../../vocabulary"
 module Hecks
   module Bluebook
     module Expression
+      # The boolean/comparison layer of a predicate's expression grammar —
+      # parses a canonical predicate string into an Or/And/Not/Compare/
+      # Include/Resolve AST (cached per distinct string, `ast_cache`) and
+      # interprets it against a call's own state/attrs. Leaf `Resolve`
+      # nodes delegate to `Resolver` for the dotted/arithmetic
+      # sub-grammar; `OPERATORS` is the comparison table projected from
+      # the grammar chapter (`PROJECTION`).
       module Evaluator
         Operator = Struct.new(:symbol, :compares_less_than, :compares_equal, :negated, keyword_init: true)
 
@@ -58,6 +65,54 @@ module Hecks
           interpret(ast_cache[expr] ||= parse(expr), state, attrs)
         end
 
+        # THE RULE-SHAPED ENTRY — evaluates a Given/Invariant (anything
+        # answering `canonical` and `ast`) by walking its STRUCTURED form,
+        # never re-parsing the text: the one parse happened at DSL-build
+        # time behind `AstJson`, and `AstReader` turns that tree back into
+        # the same nodes `parse` would have built (the equivalence is
+        # pinned by spec/expression_ast_spec.rb over the bounded-
+        # exhaustive generator). A rule with no `ast` (an Assembly-
+        # rebuilt one, or a placeholder resolved outside build_rule)
+        # falls back to parsing its canonical — same cache, same key.
+        #
+        # HECKS_EVAL=string reverts to the text path wholesale, kept for
+        # one release as the escape hatch while the ast path beds in.
+        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
+
+        def nodes_for(rule)
+          rule.ast ? AstReader.read_predicate(rule.ast) : parse(rule.canonical)
+        end
+
+        # A refused `given`/`ensures`/`invariant` names its own DESCRIPTION
+        # ("not already superseded") but, on its own, not what the block
+        # actually evaluated to — the difference between "the rule is right
+        # and my data is wrong" and "the rule is subtly wrong" is often just
+        # seeing the two operands. Scoped to the single shape that has one
+        # honest answer: `expr`'s own TOP-LEVEL node is a bare `Compare` —
+        # not `Or`/`And`/`Not` (which of several sub-comparisons would even
+        # be "the" one at fault is genuinely ambiguous), `Include` (no
+        # left/right to show), or `Resolve` (a bare boolean read, nothing to
+        # compare against). Values are rendered with `Rendering.describe`,
+        # the same house style every other refusal already prints a value
+        # through. Returns `nil` — not raised — on anything else, INCLUDING
+        # an operand that itself fails to resolve (`EvaluationError`): a
+        # missing diagnostic is a worse debugging experience than none, a
+        # crash while building one is worse still.
+        def comparison_detail(expr, state, attrs = {})
+          node = ast_cache[expr] ||= parse(expr)
+          return nil unless node.is_a?(Compare)
+
+          lhs = Resolver.interpret(node.left, state, attrs)
+          rhs = Resolver.interpret(node.right, state, attrs)
+          "left: #{Resolver.describe(lhs)}, right: #{Resolver.describe(rhs)}"
+        rescue EvaluationError
+          nil
+        end
+
         def parse(expr)
           expr = strip_parens(expr.to_s.strip)
 
@@ -117,21 +172,21 @@ module Hecks
           end
         end
 
-        def compare(op, left, right, state, attrs)
+        def compare(comparator, left, right, state, attrs)
           lhs = Resolver.interpret(left, state, attrs)
           rhs = Resolver.interpret(right, state, attrs)
 
-          apply(op, lhs, rhs)
+          apply(comparator, lhs, rhs)
         end
 
         # The algebra itself, on values already resolved — split out so a sign
         # test (SignTest#compares_via names an Operator symbol) can apply the
         # SAME primitives compare() uses against the literal 0, rather than
         # re-deriving positive?/negative?/zero? by hand a second time.
-        def apply(op, lhs, rhs)
-          result = (op.compares_less_than && less_than(lhs, rhs)) ||
-                   (op.compares_equal && equal?(lhs, rhs))
-          op.negated ? !result : result
+        def apply(comparator, lhs, rhs)
+          result = (comparator.compares_less_than && less_than(lhs, rhs)) ||
+                   (comparator.compares_equal && equal?(lhs, rhs))
+          comparator.negated ? !result : result
         end
 
         def less_than(lhs, rhs)
@@ -198,9 +253,7 @@ module Hecks
           case (found = Resolver.interpret(haystack, state, attrs))
           when Array then found.any? { |item| equal?(item, wanted) }
           when String
-            unless wanted.is_a?(String)
-              raise EvaluationError, "no implicit conversion of #{class_of(wanted)} into String"
-            end
+            raise EvaluationError, "no implicit conversion of #{class_of(wanted)} into String" unless wanted.is_a?(String)
 
             found.include?(wanted)
           else false
@@ -286,9 +339,9 @@ module Hecks
             # its own (`[0, 0 + 0]`) used to read as a split point for
             # THIS expression's own boolean/comparison grammar, exactly
             # the way an un-tracked `{`/`}` once did for block predicates.
-            elsif char == "(" || char == "{" || char == "["
+            elsif ["(", "{", "["].include?(char)
               depth += 1
-            elsif char == ")" || char == "}" || char == "]"
+            elsif [")", "}", "]"].include?(char)
               depth -= 1
             elsif depth.zero? && expr[index, operator.length] == operator
               return index if !block_given? || yield(index)

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

@@ -197,6 +197,18 @@
       "category": "positional",
       "precedence": 7,
       "arity": 1
+    },
+    {
+      "symbol": ".set?",
+      "category": "presence",
+      "precedence": 7,
+      "arity": 1
+    },
+    {
+      "symbol": ".unset?",
+      "category": "presence",
+      "precedence": 7,
+      "arity": 1
     }
   ],
   "normalisations": [

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

@@ -12,6 +12,9 @@
 module Hecks
   module Bluebook
     module Expression
+      # Reopens the SAME `Resolver` module resolver.rb defines — see this
+      # file's own header comment above for why the block-predicate/find
+      # family lives here rather than in resolver.rb itself.
       module Resolver
         # `receiver.all? { |x| PREDICATE }` / `.any? { ... }` / `.none? {
         # ... }` -- vendored addition, not (yet) upstream hecks
@@ -184,9 +187,7 @@ module Hecks
         # just `attrs` extended with the bound name for the span of that
         # one predicate evaluation, discarded immediately after.
         def evaluate_block_predicate(node, collection, state, attrs)
-          unless collection.is_a?(Array)
-            raise EvaluationError, "#{node.mode}? expects a list, got #{describe(collection)}"
-          end
+          raise EvaluationError, "#{node.mode}? expects a list, got #{describe(collection)}" unless collection.is_a?(Array)
 
           outcomes = collection.map { |element| interpret_with_element(node, element, state, attrs) }
 

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

@@ -8,6 +8,14 @@ module Hecks
     module Expression
       class EvaluationError < StandardError; end
 
+      # The dotted/arithmetic leaf grammar a predicate's `Resolve` node
+      # bottoms out in — attribute lookups, literals, arithmetic, and the
+      # growing set of vendored method-call suffixes (`.match?`,
+      # `.present?`/`.blank?`, `.set?`/`.unset?`, `.split`, `.first`/
+      # `.last`, `.all?`/`.any?`/`.none?`/`.find`, ...) this file and its
+      # `resolver/block_predicates.rb` sibling parse and interpret. Each
+      # leaf's `parse` is a pure function of its own string, cached at the
+      # `Evaluator` layer; `interpret` reads state/attrs fresh each call.
       module Resolver
         SIGN_TESTS = Hecks::Vocabulary.fetch("SignTest")
 
@@ -109,6 +117,24 @@ module Hecks
         # field that could legitimately be "" rather than absent.
         Presence       = Struct.new(:receiver, :negated, keyword_init: true)
 
+        # `.set?`/`.unset?` -- sibling of `.present?`/`.blank?` immediately
+        # above, added for a DELIBERATELY narrower question, spelled out in
+        # the name so choosing between the two pairs is a choice, not a
+        # trap: `.present?` means "not EMPTY" (Rails-standard -- nil/false,
+        # and an EMPTY String/Array/Hash, are blank; nothing else is),
+        # which quietly answers "was this ever assigned" and "does the
+        # assigned value happen to be empty" as the SAME question. For an
+        # optional field whose only legitimate unset state IS nil, that
+        # conflation is a real trap -- confirmed live: a corpus author
+        # reaching for `superseded_by.blank?` to guard an optional
+        # reference burned real time before landing on "just don't guard
+        # it," because `.blank?` cannot be asked to mean ONLY "was this
+        # never assigned." `.set?`/`.unset?` ask exactly that, and nothing
+        # else: `!receiver.nil?`, full stop -- an assigned-but-empty
+        # String/Array/Hash (or a VO wrapping one) is `.set?`, not
+        # `.unset?`, unlike `.blank?`'s own reading of the identical value.
+        Assignment     = Struct.new(:receiver, :negated, keyword_init: true)
+
         # `receiver.split("SEP")` -- vendored addition, not (yet) upstream
         # hecks (migration plan task 9): confirmed the single
         # highest-value new finding of the real-dispatch smoke sweep --
@@ -186,6 +212,18 @@ module Hecks
           interpret(parse(expr), state, attrs)
         end
 
+        # A grammar's own dispatch table — one `return Node.new(...) if
+        # expr =~ /pattern/` per leaf production, in a FIXED precedence
+        # order (`.length` before the generic suffixes, sign tests before
+        # the rest, etc. — see this file's own history comments on why
+        # several of these were added in exactly this position). Each
+        # branch is already one line; splitting the table into smaller
+        # methods would not shrink any single check, only hide the
+        # precedence order this method's own line-by-line sequence IS.
+        # rubocop:disable-next Metrics/AbcSize
+        # rubocop:disable-next Metrics/CyclomaticComplexity
+        # rubocop:disable-next Metrics/MethodLength
+        # rubocop:disable-next Metrics/PerceivedComplexity
         def parse(expr)
           expr = expr.to_s.strip
 
@@ -215,7 +253,7 @@ module Hecks
 
           return Size.new(receiver: parse(Regexp.last_match(1))) if expr =~ /\A(.+)\.size\z/
 
-          if expr =~ /\A(.+)\.match\?\(\/(.*)\/([a-z]*)\)\z/m
+          if expr =~ %r{\A(.+)\.match\?\(/(.*)/([a-z]*)\)\z}m
             return MatchesRegex.new(receiver: parse(Regexp.last_match(1)),
                                     pattern:  Regexp.last_match(2),
                                     flags:    Regexp.last_match(3))
@@ -224,19 +262,25 @@ module Hecks
           return Presence.new(receiver: parse(Regexp.last_match(1)), negated: false) if expr =~ /\A(.+)\.present\?\z/
           return Presence.new(receiver: parse(Regexp.last_match(1)), negated: true)  if expr =~ /\A(.+)\.blank\?\z/
 
+          return Assignment.new(receiver: parse(Regexp.last_match(1)), negated: false) if expr =~ /\A(.+)\.set\?\z/
+          return Assignment.new(receiver: parse(Regexp.last_match(1)), negated: true)  if expr =~ /\A(.+)\.unset\?\z/
+
           if expr =~ /\A(.+)\.split\("([^"]*)"\)\z/
-            return Split.new(receiver: parse(Regexp.last_match(1)), separator: Regexp.last_match(2))
+            return Split.new(receiver:  parse(Regexp.last_match(1)),
+                             separator: Regexp.last_match(2))
           end
 
           return First.new(receiver: parse(Regexp.last_match(1))) if expr =~ /\A(.+)\.first\z/
           return Last.new(receiver: parse(Regexp.last_match(1))) if expr =~ /\A(.+)\.last\z/
 
           if expr =~ /\A(.+)\.start_with\?\("([^"]*)"\)\z/
-            return StartsWith.new(receiver: parse(Regexp.last_match(1)), substring: Regexp.last_match(2))
+            return StartsWith.new(receiver:  parse(Regexp.last_match(1)),
+                                  substring: Regexp.last_match(2))
           end
 
           if expr =~ /\A(.+)\.end_with\?\("([^"]*)"\)\z/
-            return EndsWith.new(receiver: parse(Regexp.last_match(1)), substring: Regexp.last_match(2))
+            return EndsWith.new(receiver:  parse(Regexp.last_match(1)),
+                                substring: Regexp.last_match(2))
           end
 
           block_opener = parse_block_opener(expr)
@@ -252,6 +296,16 @@ module Hecks
           SignTest.new(operator: operator, test: test, receiver: parse(receiver))
         end
 
+        # `parse`'s own dispatch table, mirrored: one `when` per leaf node
+        # type it can produce, each already delegating to a small named
+        # helper (add, apply_sign_test, emptiness_of, ...) — the case
+        # itself IS the closed, declared set this method exists to
+        # exhaust; the `else` backstop's own comment explains why a
+        # missing arm is a bug this method is built to make loud, not
+        # quiet.
+        # rubocop:disable-next Metrics/AbcSize
+        # rubocop:disable-next Metrics/CyclomaticComplexity
+        # rubocop:disable-next Metrics/MethodLength
         def interpret(node, state, attrs)
           case node
           when IntegerLiteral, FloatLiteral, StringLiteral, BoolLiteral then node.value
@@ -274,6 +328,9 @@ module Hecks
           when Presence
             present = !blank?(interpret(node.receiver, state, attrs))
             node.negated ? !present : present
+          when Assignment
+            set = !interpret(node.receiver, state, attrs).nil?
+            node.negated ? !set : set
           when Split
             split_value(interpret(node.receiver, state, attrs), node.separator)
           when Last
@@ -339,8 +396,7 @@ module Hecks
         # found live while building this, not assumed).
         def matches_regex?(receiver_value, pattern, flags)
           text = case receiver_value
-                 when String, Symbol then receiver_value.to_s
-                 when Integer, Float then receiver_value.to_s
+                 when String, Symbol, Integer, Float then receiver_value.to_s
                  when NilClass then ""
                  else
                    raise EvaluationError, "match? expects a scalar, got #{receiver_value.class}"
@@ -442,8 +498,25 @@ module Hecks
           nil
         end
 
+        # Integer is signed 64-bit (C3.3, docs/semantics/bluebook-semantics.md)
+        # — Ruby's own Integer would promote past ±2^63-1 silently; the
+        # language does not, so a sum outside that range is an evaluation
+        # fault, worded exactly as the Rust kernel's `checked_add` words
+        # it. A Float sum that is not finite is the same fault (C3.4).
+        INT64_RANGE = (-(2**63))..((2**63) - 1)
+
         def add(left, right)
-          require_number(left, "addition") + require_number(right, "addition")
+          lhs = require_number(left, "addition")
+          rhs = require_number(right, "addition")
+          sum = lhs + rhs
+          if sum.is_a?(Integer)
+            return sum if INT64_RANGE.cover?(sum)
+
+            raise EvaluationError, "addition overflowed: #{lhs} + #{rhs} does not fit in a 64-bit integer"
+          end
+          return sum if sum.finite?
+
+          raise EvaluationError, "addition overflowed: #{lhs} + #{rhs} is not a finite number"
         end
 
         def quoted?(expr)
@@ -533,10 +606,9 @@ module Hecks
 
         def string_of(value)
           case value
-          when String                then value
-          when Integer, Float        then value.to_s
-          when TrueClass, FalseClass then value.to_s
-          when NilClass              then ""
+          when String then value
+          when Integer, Float, TrueClass, FalseClass then value.to_s
+          when NilClass then ""
           else
             raise EvaluationError, "to_s expects a scalar, got #{describe(value)}"
           end

data/lib/hecks/bluebook/expression.rb

@@ -11,4 +11,5 @@ end
 require_relative "expression/canonical_form"
 require_relative "expression/resolver"
 require_relative "expression/evaluator"
+require_relative "expression/ast_reader"
 require_relative "expression/ast_json"

data/lib/hecks/bluebook/hexagon.rb

@@ -18,6 +18,11 @@ module Hecks
       def aggregate_name = Naming.demodulise(aggregate)
     end
 
+    # The built form of a `.hecksagon` file, produced by
+    # `DSL::HecksagonBuilder` — a domain's own binds (`Bind`, above),
+    # subscriptions, and attached framework/vendored members.
+    # `Behaviour::Hecksagon` supplies the bind lookups (`bind_for`/
+    # `binds_for`); this class holds only the declared data.
     class Hecksagon
       include Hecks::IR
       include Behaviour::Hecksagon
@@ -41,6 +46,11 @@ module Hecks
       end
     end
 
+    # The built form of a `.world` file, produced by `DSL::WorldBuilder` —
+    # a domain's own `realm`/`latest` version markers and its adapter bind
+    # SETTINGS (as opposed to `Hecksagon`'s own bind LIST, above).
+    # `Behaviour::World` supplies the settings lookups (`for_verb`/
+    # `for_binding`); this class holds only the declared data.
     class World
       include Hecks::IR
       include Behaviour::World

data/lib/hecks/bluebook/lifecycle.rb

@@ -2,6 +2,10 @@ require_relative "behaviour/lifecycle"
 
 module Hecks
   module Bluebook
+    # One declared `transition` row — the state a command moves an
+    # aggregate or entity TO, and, when guarded, the state(s) it must
+    # currently be in (`from:`) for the transition to apply. An unguarded
+    # transition (`from: nil`) applies from any current state.
     class StateTransition
       attr_reader :target, :from
 
@@ -17,6 +21,11 @@ module Hecks
       def constrained? = !@from.nil?
     end
 
+    # The built form of a `lifecycle :field, default: ... do ... end`
+    # block, produced by `DSL::LifecycleBuilder` — the field a state
+    # machine lives on, its starting value, and the declared transition
+    # table. `Behaviour::Lifecycle` supplies the reads (`states`,
+    # `target_for`, ...) built purely from this data.
     class Lifecycle
       include Hecks::IR
       include Behaviour::Lifecycle

data/lib/hecks/bluebook/meta_validator/judge.rb

@@ -99,7 +99,7 @@ module Hecks
           value
         end
 
-        def args(pairs) = pairs.reject { |_, value| value.nil? }
+        def args(pairs) = pairs.compact
 
         def offer(label)
           yield
@@ -352,7 +352,10 @@ module Hecks
         # meta store happened to iterate in insertion order — an accident that an
         # ask ordered any other way would have taken away, and Reconstruction is
         # the one reader that must have the SOURCE'S order rather than a stable one.
-        POSITION = "position"
+        # `private` above has no effect on a constant; kept here anyway,
+        # beside the method that reads it, for the narrative.
+        # rubocop:disable-next Lint/UselessConstantScoping
+        POSITION = "position".freeze
 
         def declare(plan, category, node, id, parent_id, index, extra = {})
           return unless plan.declare
@@ -425,7 +428,7 @@ module Hecks
           category == "Entity" ? parent_id : id
         end
 
-        def sealers(plan, category, receiver)
+        def sealers(plan, _category, receiver)
           id = receiver[:entities].last || receiver[:aggregate]
           plan.sealers.each { |verb| send_to("Bluebook::#{verb_for(plan, verb)}", id, to: receiver) }
         end
@@ -586,7 +589,10 @@ module Hecks
         # `field_value` ; it is read the same way `plan.parent_key` already is,
         # because it IS that fact, spelled for the walk's immediate parent
         # rather than for one specific kind of one.
-        OWNER = "owner_id"
+        # `private` above has no effect on a constant; kept here anyway,
+        # beside the method that reads it, for the narrative.
+        # rubocop:disable-next Lint/UselessConstantScoping
+        OWNER = "owner_id".freeze
 
         def identity_part(plan, path, parent_id, node, index, category)
           head = path.to_s.split(".").first

data/lib/hecks/bluebook/meta_validator/plan.rb

@@ -35,6 +35,10 @@ module Hecks
       # nothing — that is the judge's job.
       class Plan
         # One append command: the verb, and the value-object-field -> argument map.
+        # `:map` shadows Enumerable#map on purpose — `spec/plan_spec.rb`
+        # itself asserts `appends["emits"].map` reads the field (a Hash),
+        # not an Enumerable#map result. Verified before disabling this cop.
+        # rubocop:disable-next Lint/StructNewOverride
         Append = Struct.new(:verb, :map, keyword_init: true)
 
         # One setting command. `targets` is target -> argument ; Lifecycle sets two

data/lib/hecks/bluebook/meta_validator/reconstruction.rb

@@ -148,7 +148,7 @@ module Hecks
         # against, so the entity ones have to be told apart by `entity_id`. Rejecting
         # from an ORDERED read keeps the order.
         def own(category, aggregate_id)
-          declared(category, aggregate_id).reject { |row| text(row[:entity_id]).to_s != "" }
+          declared(category, aggregate_id).select { |row| text(row[:entity_id]).to_s == "" }
         end
 
         # A piece's own verbs and asks. There is no `DeclaredIn` keyed by entity, so

data/lib/hecks/bluebook/meta_validator/shapes.rb

@@ -238,12 +238,12 @@ module Hecks
         # Mutation's own `to_h` lambda does, rather than leaving the key
         # silently absent (spec/round_trip_spec's whole point: a field the
         # language does not hold is a named gap, not a byte-for-byte one).
-        def mutation(target, op, bindings)
-          base = { target: target.to_sym, op: op.to_sym, sign: Hecks::Bluebook::Mutation.sign_for(op) }
+        def mutation(target, oper, bindings)
+          base = { target: target.to_sym, op: oper.to_sym, sign: Hecks::Bluebook::Mutation.sign_for(oper) }
           # `:delegate`/`:corrects` (CommandBuilder#delegates_to's and
           # #corrects_impl's own comments) ride the SAME multi-binding
           # shape `:append` does.
-          return base.merge(fields: appended(bindings)) if ["append", "delegate", "corrects"].include?(op)
+          return base.merge(fields: appended(bindings)) if ["append", "delegate", "corrects"].include?(oper)
 
           base.merge(source: classified(bindings.first))
         end

data/lib/hecks/bluebook/meta_validator/syntax_boot.rb

@@ -85,7 +85,9 @@ module Hecks
 
         def same_chapters?(cached, current)
           cached.size == current.size &&
-            cached.zip(current).all? { |(cached_name, cached_chapter), (name, chapter)| cached_name == name && cached_chapter.equal?(chapter) }
+            cached.zip(current).all? do |(cached_name, cached_chapter), (name, chapter)|
+              cached_name == name && cached_chapter.equal?(chapter)
+            end
         end
 
         def boot
@@ -140,7 +142,8 @@ module Hecks
         def declare_syntax(runtime, bluebook)
           syntax = bluebook.aggregate("Syntax")
           runtime.dispatch("Bluebook::Bluebook.Declare", name:           v(bluebook.hecks_name),
-                                                         vision:         v("the language's own grammar table, dispatched into itself"),
+                                                         vision:         v("the language's own grammar table, " \
+                                                                           "dispatched into itself"),
                                                          classification: v("core"))
           runtime.dispatch("Bluebook::Syntax.Declare", bluebook: bluebook.hecks_name, name: v(syntax.hecks_name))
         end
@@ -239,8 +242,8 @@ module Hecks
         end
 
         def stringify(row)
-          row.to_h.each_with_object({}) do |(key, cell), out|
-            out[key] = scalar(cell).to_s
+          row.to_h.transform_values do |cell|
+            scalar(cell).to_s
           end
         end