hecks 2.8.0 → 2.9.0

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

@@ -8,53 +8,23 @@ 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.
+      # The dotted/arithmetic leaf grammar a predicate's `Resolve` node bottoms out in.
+      # `parse` is a pure function of its string; `interpret` reads state/attrs fresh.
       module Resolver
         SIGN_TESTS = Hecks::Vocabulary.fetch("SignTest")
 
-        # Which Comparison operator each sign test is sugar for, against the
-        # literal 0 — Vocabulary::SignTest's own compares_via
-        # (language/bluebook/vocabulary.bluebook), read off the generated
-        # table rather than typed a second time.
+        # Comparison operator each sign test stands for, against the literal 0.
         SIGN_TEST_OPERATORS = Hecks::Vocabulary.rows("SignTest")
                                                .to_h { |row| [row["name"], row["compares_via"]] }
                                                .freeze
 
-        # The leaf grammar an expression's dotted/arithmetic side parses into.
-        # Which node a string produces is a pure function of the string, so
-        # parse() runs once per distinct leaf (folded into Evaluator's own
-        # ast_cache — see evaluator.rb) and interpret() reads state/attrs
-        # fresh on every call. Only Lookup — the true leaf — ever touches
-        # state/attrs.
+        # Leaf nodes of the grammar. Only Lookup touches state/attrs.
         IntegerLiteral = Struct.new(:value, keyword_init: true)
         FloatLiteral   = Struct.new(:value, keyword_init: true)
         StringLiteral  = Struct.new(:value, keyword_init: true)
         BoolLiteral    = Struct.new(:value, keyword_init: true)
-        # `["active", "suspended"]` — a literal set, the haystack half of
-        # an `.include?`. Vocabulary::IncludeHaystack has always admitted
-        # Array (and Evaluator#includes? has always had a `when Array`
-        # arm), but nothing could produce one: there was no array-literal
-        # node, so `["a", "b"].include?(x)` fell through to Lookup and
-        # refused with `cannot resolve "[\"a\", \"b\"]"`. A declared
-        # capability with no way to spell it.
         ArrayLiteral   = Struct.new(:elements, keyword_init: true)
-        # A plain class, not `Struct.new(keyword_init: true)` — every
-        # sibling leaf node here carries at least one field, but this
-        # one carries none by nature (a nil literal has no data to
-        # hold), and `Struct.new` with zero member names ahead of
-        # `keyword_init:` is real, live Ruby-version-dependent
-        # behavior: works on 3.3, raises "wrong number of arguments
-        # (given 0, expected 1+)" on 3.2 (caught deploying to Lambda's
-        # own ruby3.2 runtime). `.new`/`case ... when NilLiteral` below
-        # are the only two things this type is ever used for, and a
-        # bare class answers both identically.
+        # A plain class: `Struct.new(keyword_init: true)` with no members raises on Ruby 3.2.
         NilLiteral     = Class.new
         Addition       = Struct.new(:left, :right, keyword_init: true)
         SignTest       = Struct.new(:operator, :test, :receiver, keyword_init: true)
@@ -64,186 +34,39 @@ module Hecks
         Size           = Struct.new(:receiver, keyword_init: true)
         Lookup         = Struct.new(:path, keyword_init: true)
 
-        # Update 2026-08-27: every "vendored addition, not (yet) upstream
-        # hecks" comment on this file's own MatchesRegex/Presence/Split/
-        # First/Last/StartsWith/EndsWith below (plus ArrayLiteral above)
-        # described a real gap, found the hard way, in the history each
-        # comment tells — and that history stays exactly as written,
-        # on purpose. What changed is the present tense claim "not (yet)
-        # upstream": a review of this exact migration found these eight
-        # symbols had working Ruby parse/interpret arms but had never
-        # gone through Propose -> Render -> Admit
-        # (lib/hecks/grammar/expression_operators.json) the way every
-        # other operator here has — a closed-vocabulary guard
-        # (spec/operator_conformance_spec.rb) built entirely over tables
-        # structurally could not see hand-coded Struct/parse/interpret
-        # additions, so eight operators ran in Ruby, admitted nowhere,
-        # invisible to the one guard whose whole job was "reads in every
-        # target." All eight are now ledger-admitted for real, with full
-        # Rust kernel parity (rust/src/kernel/expression_operators/
-        # {pattern_match,presence,text,positional}.rs) — the two-tier
-        # gap is closed, not merely tracked.
-        #
-        # `receiver.match?(/pattern/)` -- vendored addition, not (yet)
-        # upstream hecks (migration plan task 8): confirmed the
-        # single most impactful corpus-wide dispatch-time gap of the
-        # whole migration -- `.match?(regex)` appears in nearly every
-        # value_object's format-validation rule across every corpus
-        # this migration touched (email/phone/ISO-8601-timestamp/zip
-        # patterns, dozens of files), and had no parse support at all:
-        # it fell all the way through to the `Lookup` catch-all below,
-        # which tried to split the entire ".match?(/\A\d{5}\z/)" text
-        # on "." as if it were a dotted attribute path, and crashed with
-        # an opaque "no implicit conversion of Symbol into Integer"
-        # somewhere downstream -- confirmed live via a real dispatch,
-        # not validate (validate never evaluates a predicate body).
-        # `receiver` still needs its own parse (it may itself be a
-        # dotted lookup, e.g. `some_field.match?(...)`), the pattern
-        # text is taken as-is between the slashes (a Ruby Regexp literal,
-        # not the evaluator's own mini-grammar -- there is nothing to
-        # recurse into).
         MatchesRegex   = Struct.new(:receiver, :pattern, :flags, keyword_init: true)
 
-        # `.present?`/`.blank?` -- vendored addition, not (yet) upstream
-        # hecks (migration plan task 8): the second-most pervasive
-        # gap this pass found, right behind `.match?` -- confirmed real
-        # via the same "no such attribute" Lookup-fallback crash, since
-        # neither suffix existed in this leaf grammar at all. Rails-
-        # standard semantics (blank = nil, or responds_to?(:empty?) &&
-        # empty? ; present = !blank), not just `!nil?` -- matches what
-        # every corpus author actually means by `.present?` on a string
-        # 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.
+        # `.set?`/`.unset?` ask only `!nil?`; unlike `.blank?`, an assigned empty value is set.
         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 --
-        # the bus's own core `Phrase` value object (dispatch/lexicon/
-        # query/command_bus.bluebook, all four storehouse-kernel files,
-        # byte-identical text) validates its four-segment shape with
-        # `value.split("::").length == 4 && value.split("::").all? { |s|
-        # s.length > 0 }` -- `.split(` matched none of this grammar's
-        # known suffixes, so it fell through to the `Lookup` catch-all,
-        # which split the raw expression text on "." (not the runtime
-        # value) and crashed with `TypeError: no implicit conversion of
-        # Symbol into Integer` the moment `String#[]` was handed a
-        # Symbol segment -- meaning every command taking a Phrase was
-        # entirely undispatchable, confirmed live via `Lexicon::Lexicon.
-        # Lookup`/`Query::Query.Run`, not inferred. Produces a real
-        # Array, deliberately not a scalar -- `.length`/`.all?` compose
-        # with it below the same way they compose with any other
-        # receiver, because `parse` recurses on the receiver text and
-        # the existing `Size` node (`.length`/`.size`) already treats
-        # "whatever `interpret` returns" as its receiver's value, not a
-        # fixed type. Separator is taken literally between the quotes,
-        # same "no sub-grammar to recurse into" precedent `MatchesRegex`
-        # already set for its own `/pattern/` text above.
         Split          = Struct.new(:receiver, :separator, keyword_init: true)
 
-        # `receiver.last` -- vendored addition, not (yet) upstream
-        # hecks (migration plan task 9), same pass as `Split` above
-        # and built for the same `Phrase`/`Path` value objects --
-        # `Query::Phrase`'s own invariant chains `.split("::").last.
-        # match?(...)` to check the fourth segment's casing. Same shape
-        # as `.length`/`.size` (Size) and `.empty?` (Empty) -- a plain
-        # receiver-in, scalar-out accessor, no sub-grammar of its own.
         Last           = Struct.new(:receiver, keyword_init: true)
 
-        # `receiver.first` -- sibling addition to `Last` immediately
-        # above, same shape, same vendored-not-upstream status. Added
-        # for the shipping domain's `legs.first` (an itinerary's
-        # departure leg), the exact mirror of `legs.last` (its arrival
-        # leg) that domain already leaned on -- `Last`'s own duck-typed-
-        # on-`respond_to?` reasoning applies unchanged, so `first_of`
-        # below is `last_of` with the one method swapped, not a new
-        # design.
         First          = Struct.new(:receiver, keyword_init: true)
 
-        # `receiver.start_with?("prefix")` / `receiver.end_with?("suffix")`
-        # -- vendored addition, not (yet) upstream hecks (migration
-        # plan task 9), the sibling gap the `Split`/`Last`/`BlockPredicate`
-        # pass above flagged and deliberately left unfixed --
-        # `Query::Query.Run`/`Dispatch::Dispatch.Route`/`CommandBus::
-        # CommandBus.Route`'s shared `Params` value object validates its
-        # JSON-object shape with `value.start_with?("{") && value.
-        # end_with?("}")` (dispatch/query/command_bus.bluebook, all three
-        # storehouse-kernel files, byte-identical text) -- `.start_with?(`/
-        # `.end_with?(` matched none of this grammar's known suffixes, so
-        # both fell through to the `Lookup` catch-all and crashed with the
-        # same `TypeError: no implicit conversion of Symbol into
-        # Integer` shape any unsupported suffix produces here, confirmed
-        # live via a real dispatch (not validate), not inferred. Two
-        # separate node types rather than one `mode:`-keyed struct (the `BlockPredicate`/
-        # `SignTest` precedent) -- `start_with?`/`end_with?` aren't two
-        # spellings of the same test the way `all?`/`any?`/`none?` are (one
-        # Array-aggregation family) or `positive?`/`negative?`/`zero?` are
-        # (one comparison-against-0 family) ; they check different ends of
-        # the same string and share nothing but their
-        # receiver-plus-literal-argument shape. `substring` is taken
-        # literally between the quotes, same "no sub-grammar to recurse
-        # into" precedent `Split`'s `separator`/`MatchesRegex`'s `pattern`
-        # already set.
         StartsWith = Struct.new(:receiver, :substring, keyword_init: true)
         EndsWith   = Struct.new(:receiver, :substring, keyword_init: true)
 
         module_function
 
-        # Parses and interprets `expr` in one step, without going through
-        # `Evaluator`'s own boolean/comparison grammar or its `ast_cache` —
-        # for a caller that wants this leaf grammar's own raw value (an
-        # Integer, a String, an Array, ...), not a boolean.
+        # Parses and interprets `expr` in one step, bypassing `Evaluator`'s boolean grammar.
         #
-        # @param expr [String] the dotted/arithmetic leaf expression to
-        #   resolve
-        # @param state [Hash{Symbol => Object}] the stored attribute values
-        #   an unqualified name may resolve against
-        # @param attrs [Hash{Symbol => Object}] the call's own argument
-        #   values, checked before `state`
-        # @return [Object] whatever `expr` resolves to: an Integer, Float,
-        #   String, `true`/`false`, `nil`, or Array, depending on `expr`'s
-        #   own leaf grammar
-        # @raise [EvaluationError] if `expr` names an attribute or argument
-        #   neither `attrs` nor `state` has, or if an operation in `expr`
-        #   is applied to a value of the wrong type
+        # @param expr [String] the dotted/arithmetic leaf expression
+        # @param state [Hash{Symbol => Object}] stored attribute values
+        # @param attrs [Hash{Symbol => Object}] call arguments, checked before `state`
+        # @return [Object] the resolved Integer, Float, String, boolean, nil, or Array
+        # @raise [EvaluationError] on an unknown name or a wrongly typed operand
         def resolve(expr, state, attrs)
           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.
+        # Branch order is the precedence order (`.length` first, sign tests before the rest).
         #
-        # @param expr [String] the leaf expression text to parse
-        # @return [Object] the parsed leaf node — one of this module's own
-        #   Struct types (`IntegerLiteral`, `FloatLiteral`, `StringLiteral`,
-        #   `BoolLiteral`, `NilLiteral`, `ArrayLiteral`, `Addition`,
-        #   `SignTest`, `Empty`, `ToS`, `Modulo`, `Size`, `MatchesRegex`,
-        #   `Presence`, `Assignment`, `Split`, `First`, `Last`,
-        #   `StartsWith`, `EndsWith`, `BlockPredicate`, `Find`), chosen by
-        #   `expr`'s own shape, or `Lookup` when nothing else matches
+        # @param expr [String] the leaf expression text
+        # @return [Object] the parsed leaf node, or `Lookup` when nothing else matches
         # rubocop:disable-next Metrics/AbcSize
         # rubocop:disable-next Metrics/CyclomaticComplexity
         # rubocop:disable-next Metrics/MethodLength
@@ -313,13 +136,6 @@ module Hecks
           Lookup.new(path: expr)
         end
 
-        # Builds the `SignTest` node for a matched `.positive?`/
-        # `.negative?`/`.zero?`-style suffix.
-        #
-        # @param parts [Array(String, String)] the `[receiver_text,
-        #   test_name]` pair `match_suffix` returns
-        # @return [SignTest] the parsed sign-test node, its `receiver`
-        #   itself parsed
         def sign_test_node(parts)
           receiver, test = parts
           symbol   = SIGN_TEST_OPERATORS.fetch(test)
@@ -327,28 +143,10 @@ 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.
+        # Evaluates a node `parse` produced against `state` and `attrs`.
         #
-        # @param node [Object] a node `parse` produced (one of this
-        #   module's own Struct types) or built directly by a caller
-        # @param state [Hash{Symbol => Object}] the stored attribute values
-        #   a `Lookup` node may resolve against
-        # @param attrs [Hash{Symbol => Object}] the call's own argument
-        #   values, checked before `state`
-        # @return [Object] the value `node` resolves to: an Integer, Float,
-        #   String, `true`/`false`, `nil`, or Array, depending on `node`'s
-        #   own type
-        # @raise [EvaluationError] if `node` is not one of the handled
-        #   types, or if a helper it dispatches to (`add`, `apply_sign_test`,
-        #   `matches_regex?`, `split_value`, `last_of`, `first_of`,
-        #   `starts_with?`, `ends_with?`, `apply_modulo`, `size_of`,
-        #   `emptiness_of`, `lookup`) refuses its operand
+        # @return [Object] the value the node resolves to
+        # @raise [EvaluationError] if the node type is unhandled or an operand is refused
         # rubocop:disable-next Metrics/AbcSize
         # rubocop:disable-next Metrics/CyclomaticComplexity
         # rubocop:disable-next Metrics/MethodLength
@@ -394,42 +192,16 @@ module Hecks
           when Lookup
             lookup(node.path, state, attrs)
           else
-            # Every leaf node `parse` can produce has a `when` above —
-            # a backstop against the day this grammar grows a new leaf
-            # type (this file's own history: MatchesRegex/Presence/
-            # Split/Last/First/Find/StartsWith/EndsWith/BlockPredicate
-            # were each added exactly this way, and each one — before it had an
-            # `interpret` arm — fell all the way through to the
-            # `Lookup` catch-all in `parse` and crashed downstream with
-            # an opaque type error, never here). A missing arm here
-            # would instead return bare `nil` silently, the one wrong-
-            # answer shape this leaf grammar has otherwise never
-            # allowed.
+            # A missing arm must raise; silently returning nil is the one wrong answer
+            # this grammar never allows.
             raise EvaluationError, "no interpreter handles #{node.class} — add a case before parse can produce it"
           end
         end
 
-        # `.present?`/`.blank?` -- vendored addition, see the
-        # `Presence` struct's own comment above. `nil` and `false` are
-        # blank ; a String/Array/Hash is blank when empty, not merely
-        # falsy -- a VO-wrapped field that is assigned (`{value: "x"}`,
-        # `Value#to_h`'d first) is present regardless of what its own
-        # inner value holds, matching how every VO-typed field in this
-        # corpus is actually shaped once set at all.
-        #
-        # @param value [Object] the already-interpreted receiver value
-        # @return [Boolean] `true` for `nil`, `false`, or an empty
-        #   String/Array/Hash (a to_h-able value is converted first);
-        #   `false` for anything else
         def blank?(value)
           return true if value.nil? || value == false
 
-          # Duck-typed, not `value.is_a?(Runtime::Value)` -- this module
-          # is `Bluebook::Expression`, a different namespace tree from
-          # `Runtime::Value` entirely, and reaching across for a single
-          # class check is the exact cross-module coupling that already
-          # broke `Modulo`'s own `match_call` reference elsewhere in
-          # this file (found live while building this fix, not assumed).
+          # Duck-typed: reaching across to Runtime::Value would couple the namespaces.
           value = value.to_h if value.respond_to?(:to_h) && !value.is_a?(Hash)
           case value
           when String, Array, Hash then value.empty?
@@ -437,26 +209,6 @@ module Hecks
           end
         end
 
-        # `receiver.match?(/pattern/)` -- vendored addition, see the
-        # `MatchesRegex` struct's own comment above. `receiver_value` is
-        # coerced to a plain String first -- inlined here rather than
-        # calling `Evaluator#string_of` (a different module_function
-        # module; not actually in scope from inside Resolver despite
-        # `Modulo`'s own parse rule above calling a same-named
-        # `match_call` that has the identical cross-module problem --
-        # found live while building this, not assumed).
-        #
-        # @param receiver_value [String, Symbol, Integer, Float, nil] the
-        #   already-interpreted receiver value
-        # @param pattern [String] the regex source, exactly as it appeared
-        #   between the `/.../` delimiters
-        # @param flags [String] the suffix flag letters after the closing
-        #   `/`; `"i"` enables `Regexp::IGNORECASE`, `"m"` `MULTILINE`,
-        #   `"x"` `EXTENDED`
-        # @return [Boolean] whether `pattern` matches `receiver_value`'s
-        #   string form
-        # @raise [EvaluationError] if `receiver_value` is not a scalar, or
-        #   `pattern` is not a valid regex
         def matches_regex?(receiver_value, pattern, flags)
           text = case receiver_value
                  when String, Symbol, Integer, Float then receiver_value.to_s
@@ -472,25 +224,10 @@ module Hecks
 
           Regexp.new(pattern, options).match?(text)
         rescue RegexpError => e
-          # M9: a malformed pattern between the slashes (an unclosed
-          # character class, say) is a defect in the expression text
-          # itself, exactly the same category of author mistake an
-          # unresolvable attribute name already refuses for — `Regexp.new`
-          # raising a raw `RegexpError` crossed this sublanguage's own
-          # refusal boundary the same way the `ZeroDivisionError`/
-          # `TypeError` cases elsewhere in this file did.
+          # A malformed pattern is an author mistake; refuse it as EvaluationError.
           raise EvaluationError, "match? given an invalid pattern #{pattern.inspect} — #{e.message}"
         end
 
-        # The elements of a bracketed literal, or nil if this isn't one.
-        # Splits on top-level commas only — quote-aware and depth-aware,
-        # the same discipline `split_addition` already applies, so a
-        # nested array or a comma inside a string element stays whole.
-        #
-        # @param expr [String] the leaf expression text
-        # @return [Array<String>, nil] the unparsed source text of each
-        #   element, in order (`[]` for `"[]"`), or `nil` when `expr` is
-        #   not bracketed
         def array_elements(expr)
           return nil unless expr.start_with?("[") && expr.end_with?("]")
 
@@ -523,24 +260,8 @@ module Hecks
           elements.reject(&:empty?)
         end
 
-        # Braces count toward depth, exactly as parens do — a `+` inside a
-        # block predicate's own `{ |x| ... }` body is not this expression's
-        # own addition. `parse` tries addition before `parse_block_opener`,
-        # so a paren-only depth count split
-        #   kings.any? { |k| k.square.file == to.file + 1 && ... }
-        # at that inner `+`, turning the whole expression into a nonsense
-        # Addition whose left operand then walked "any? { |k| k" into an
-        # Array as an attribute path — "TypeError: no implicit conversion
-        # of Symbol into Integer", the same signature every unsupported
-        # construct raises, which is what let this hide. Found live in a
-        # downstream chess domain's castling given; the evaluator's own
-        # top_level_index has counted braces since its own version of this
-        # exact lesson.
-        #
-        # @param expr [String] the leaf expression text
-        # @return [Array(String, String), nil] the `[left, right]` operand
-        #   text around the first top-level `+`, or `nil` when `expr` has
-        #   none
+        # Braces and brackets count toward depth like parens, so a `+` inside a block body
+        # or an array element is not this expression's own addition.
         def split_addition(expr)
           depth = 0
           quote = nil
@@ -550,17 +271,7 @@ module Hecks
               quote = nil if char == quote
             elsif ['"', "'"].include?(char)
               quote = char
-            # `[`/`]` -- the identical lesson this method's own `(`/`{`
-            # comment already names, a third time (found live via the
-            # type-directed bounded-exhaustive expression generator,
-            # Phase 7 of the equivalence-gap plan): `ArrayLiteral` can
-            # appear as a general sub-expression, not only as
-            # `.include?`'s own haystack, so without counting `[`/`]`
-            # toward depth here too, an array element containing its own
-            # top-level `+` (`[0, 0 + 0]`) reads as this expression's own
-            # addition split point -- tearing the whole receiver before
-            # `.all?`/`.any?`/etc. in half before `parse_block_opener`
-            # ever sees it as one atomic leaf.
+            # `[`/`]` count too: an array element may hold its own top-level `+`.
             elsif ["(", "{", "["].include?(char)
               depth += 1
             elsif [")", "}", "]"].include?(char)
@@ -572,23 +283,9 @@ 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).
+        # Integer is signed 64-bit; a sum outside the range is an evaluation fault (C3.3, C3.4).
         INT64_RANGE = (-(2**63))..((2**63) - 1)
 
-        # Adds two already-interpreted numeric operands, refusing an
-        # out-of-range result rather than letting it wrap or promote
-        # silently.
-        #
-        # @param left [Integer, Float] the left operand
-        # @param right [Integer, Float] the right operand
-        # @return [Integer, Float] `left + right`
-        # @raise [EvaluationError] if either operand is not numeric, or the
-        #   Integer sum falls outside signed 64-bit range, or the Float sum
-        #   is not finite
         def add(left, right)
           lhs = require_number(left, "addition")
           rhs = require_number(right, "addition")
@@ -603,12 +300,6 @@ module Hecks
           raise EvaluationError, "addition overflowed: #{lhs} + #{rhs} is not a finite number"
         end
 
-        # Reports whether `expr` is a whole string literal — `"` or `'`
-        # delimited, both ends.
-        #
-        # @param expr [String] the leaf expression text
-        # @return [Boolean] whether `expr` opens and closes with matching
-        #   quote characters
         def quoted?(expr)
           return false if expr.length < 2
 
@@ -616,135 +307,54 @@ module Hecks
             (expr.start_with?("'") && expr.end_with?("'"))
         end
 
-        # Declared the same way in Vocabulary::SizedType
-        # (language/bluebook/vocabulary.bluebook) — spec/vocabulary_conformance_spec
-        # holds this equal to the language. Shared by .size and .empty?,
-        # which admit the same set for the same reason.
+        # Held equal to Vocabulary::SizedType by spec/vocabulary_conformance_spec.
         SIZED_TYPES = Hecks::Vocabulary.fetch("SizedType")
 
-        # Counts `value`'s elements or characters, for `.length`/`.size`.
-        #
-        # @param value [Array, String, Hash] the already-interpreted
-        #   receiver value
-        # @return [Integer] the number of elements (Array/Hash) or
-        #   characters (String) `value` holds
-        # @raise [EvaluationError] if `value` is not an Array, String, or
-        #   Hash
         def size_of(value)
           return value.size if value.is_a?(Array) || value.is_a?(String) || value.is_a?(Hash)
 
           raise EvaluationError, "size expects a list or string, got #{describe(value)}"
         end
 
-        # Reports whether `value` holds no elements or characters, for
-        # `.empty?`.
-        #
-        # @param value [Array, String, Hash] the already-interpreted
-        #   receiver value
-        # @return [Boolean] whether `value` holds no elements or characters
-        # @raise [EvaluationError] if `value` is not an Array, String, or
-        #   Hash
         def emptiness_of(value)
           return value.empty? if value.is_a?(Array) || value.is_a?(String) || value.is_a?(Hash)
 
           raise EvaluationError, "empty? expects a list or string, got #{describe(value)}"
         end
 
-        # Splits `value` on `separator`, for `.split("SEP")` -- vendored
-        # addition, see the `Split` struct's own comment above. Only a
-        # String receiver makes sense to split -- unlike `.length`/`.size`/
-        # `.empty?`, which are already meaningful over Array/Hash too,
-        # `.split` is a String-only method in the corpus's own usage
-        # (every occurrence found this pass splits a Phrase's own string
-        # value).
-        #
-        # @param value [String] the already-interpreted receiver value
-        # @param separator [String] the literal separator text
-        # @return [Array<String>] `value` split on `separator`, Ruby's own
-        #   `String#split` semantics
-        # @raise [EvaluationError] if `value` is not a String
         def split_value(value, separator)
           raise EvaluationError, "split expects a string, got #{describe(value)}" unless value.is_a?(String)
 
           value.split(separator)
         end
 
-        # Returns `value`'s last element, for `.last` -- vendored
-        # addition, see the `Last` struct's own comment above. Duck-typed
-        # on `respond_to?(:last)` rather than hard-coding Array -- the one
-        # corpus usage found this pass (`Query::Phrase`'s
-        # `.split("::").last`) always receives a `Split`-produced Array,
-        # but nothing about `.last` itself is Array-specific, and this
-        # matches `Empty`/`Size`'s own duck-typed-over-a-known-set
-        # precedent without inventing a narrower rule than the method
-        # needs.
-        #
-        # @param value [#last] the already-interpreted receiver value
-        # @return [Object] `value.last`
-        # @raise [EvaluationError] if `value` does not respond to `:last`
         def last_of(value)
           return value.last if value.respond_to?(:last)
 
           raise EvaluationError, "last expects a list, got #{describe(value)}"
         end
 
-        # Returns `value`'s first element, for `.first` -- see the
-        # `First` struct's own comment above. `last_of` with the one
-        # method swapped, same duck-typed reasoning.
-        #
-        # @param value [#first] the already-interpreted receiver value
-        # @return [Object] `value.first`
-        # @raise [EvaluationError] if `value` does not respond to `:first`
         def first_of(value)
           return value.first if value.respond_to?(:first)
 
           raise EvaluationError, "first expects a list, got #{describe(value)}"
         end
 
-        # Reports whether `value` starts with `substring`, for
-        # `.start_with?("prefix")` -- vendored addition, see the
-        # `StartsWith` struct's own comment above. String-only, same
-        # reasoning as `.split` above -- every corpus usage found this
-        # pass (`Params`'s own JSON-object-shape invariant) receives a
-        # plain String field.
-        #
-        # @param value [String] the already-interpreted receiver value
-        # @param substring [String] the literal prefix text
-        # @return [Boolean] whether `value` starts with `substring`
-        # @raise [EvaluationError] if `value` is not a String
         def starts_with?(value, substring)
           raise EvaluationError, "start_with? expects a string, got #{describe(value)}" unless value.is_a?(String)
 
           value.start_with?(substring)
         end
 
-        # Reports whether `value` ends with `substring`, for
-        # `.end_with?("suffix")` -- vendored addition, see the `EndsWith`
-        # struct's own comment above. Same String-only reasoning as
-        # `start_with?` immediately above.
-        #
-        # @param value [String] the already-interpreted receiver value
-        # @param substring [String] the literal suffix text
-        # @return [Boolean] whether `value` ends with `substring`
-        # @raise [EvaluationError] if `value` is not a String
         def ends_with?(value, substring)
           raise EvaluationError, "end_with? expects a string, got #{describe(value)}" unless value.is_a?(String)
 
           value.end_with?(substring)
         end
 
-        # Declared the same way in Vocabulary::ToStringType
-        # (language/bluebook/vocabulary.bluebook) — spec/vocabulary_conformance_spec
-        # holds this equal to the language.
+        # Held equal to Vocabulary::ToStringType by spec/vocabulary_conformance_spec.
         TO_STRING_TYPES = Hecks::Vocabulary.fetch("ToStringType")
 
-        # Coerces `value` to its string form, for `.to_s`.
-        #
-        # @param value [String, Integer, Float, Boolean, nil] the
-        #   already-interpreted receiver value
-        # @return [String] `value` unchanged if already a String,
-        #   `value.to_s` for a numeric or boolean, or `""` for `nil`
-        # @raise [EvaluationError] if `value` is not one of the above
         def string_of(value)
           case value
           when String then value
@@ -755,16 +365,6 @@ module Hecks
           end
         end
 
-        # Splits `expr` at the first of `suffixes` it ends with — the
-        # shared lookup behind every `.positive?`/`.negative?`/`.zero?`-
-        # style sign test.
-        #
-        # @param expr [String] the leaf expression text
-        # @param suffixes [Array<String>] the admitted suffix names
-        #   (without the leading `.`), tried in order
-        # @return [Array(String, String), nil] the `[receiver_text,
-        #   matched_suffix]` pair for the first matching suffix, or `nil`
-        #   if none matches
         def match_suffix(expr, suffixes)
           suffixes.each do |suffix|
             marker = ".#{suffix}"
@@ -773,14 +373,6 @@ module Hecks
           nil
         end
 
-        # Applies `node`'s comparison (`positive?`/`negative?`/`zero?`)
-        # against the literal `0`, reusing `Evaluator.apply`'s own
-        # comparison primitives rather than re-deriving them by hand.
-        #
-        # @param node [SignTest] the sign-test node being evaluated
-        # @param value [Object] the already-interpreted receiver value
-        # @return [Boolean] whether `value` passes `node`'s own sign test
-        # @raise [EvaluationError] if `value` is not numeric
         def apply_sign_test(node, value)
           number = numeric(value)
           raise EvaluationError, "#{node.test} expects a number, got #{describe(value)}" unless number
@@ -788,58 +380,8 @@ module Hecks
           Evaluator.apply(node.operator, number, 0)
         end
 
-        # Found live via the type-directed bounded-exhaustive expression
-        # generator (Phase 7, equivalence-gap plan — spec/
-        # bounded_exhaustive_expression_spec.rb): `.modulo(`'s own
-        # argument position accepts any numeric sub-expression, including
-        # another `.modulo(...)` call — `0.modulo(num_b.modulo(-1))` is
-        # perfectly well-typed — but `expr.rindex(marker)` finds the
-        # rightmost (innermost) `.modulo(` in the whole string, not the
-        # outermost one a nested call needs split at. For that expression
-        # it found the inner `.modulo(` (inside `num_b.modulo(-1)`) and
-        # split there, producing a receiver of `"0.modulo(num_b"` and a
-        # divisor of `"-1)"` — both garbage, both re-parsed as bogus
-        # `Lookup` paths, both then refusing with "cannot resolve" — a
-        # silent misparse that happened to fail safe into a real
-        # `EvaluationError` rather than a raw crash, which is exactly why
-        # this had gone unnoticed: nothing before this generator existed
-        # ever fed `.modulo` a nested `.modulo` call, random fuzzing
-        # essentially never manufactures that specific shape by chance,
-        # and the resulting refusal looks like an ordinary, correct one
-        # unless you already know every name this generator's own
-        # synthetic state declares (real corpus authors would see this as
-        # a mysterious "cannot resolve" on text they never wrote).
-        #
-        # Fixed the same way `split_addition`/`Evaluator.top_level_index`
-        # already handle nested `(`/`{` elsewhere in this exact file:
-        # find the first (leftmost, outermost) occurrence of the marker,
-        # then track paren/quote depth from there to find its own
-        # matching close — not just strip the string's own trailing `)`
-        # and hope it belongs to this call.
-        # Not just the first occurrence, either — `.modulo` also chains
-        # (`x.modulo(a).modulo(b)`, the receiver of the outer call itself
-        # ending in a `.modulo(...)` call), a second real shape the
-        # leftmost-occurrence-only version of this fix still mis-parsed:
-        # the first `.modulo(`'s own matching close paren lands mid-
-        # string (right after `a)`, before the second `.modulo(b)`), so
-        # it correctly fails the "reaches the end" check below and must
-        # be tried again at the next occurrence rather than giving up.
-        # Trying occurrences strictly left to right and taking the first
-        # one whose matching close reaches the string's last character
-        # handles both shapes with the same rule: for nesting
-        # (`.modulo(x.modulo(y))`), the leftmost (outer) occurrence's own
-        # paren-depth tracking already walks straight through the inner
-        # call to the true final `)`; for chaining, the leftmost
-        # occurrence's close lands short and is rejected, so the next
-        # occurrence (the true outermost call) is tried instead.
-        #
-        # @param expr [String] the leaf expression text
-        # @param marker [String] the call-opening text to search for, such
-        #   as `".modulo("`
-        # @return [Array(String, String), nil] the `[receiver_text,
-        #   argument_text]` pair for the outermost occurrence of `marker`
-        #   whose matching close paren reaches `expr`'s last character, or
-        #   `nil` if none does
+        # Finds the outermost `marker` call whose matching `)` ends `expr`. `rindex` would split
+        # nested `.modulo(` calls at the inner one, and a first match alone mis-parses chains.
         def match_call(expr, marker)
           start = 0
           while (index = expr.index(marker, start))
@@ -851,17 +393,6 @@ module Hecks
           nil
         end
 
-        # Finds the index of the `)` that closes the `(` already consumed
-        # by the caller. `matching_brace` (resolver/block_predicates.rb)'s
-        # own twin, one bracket pair over: `start` is the index just past
-        # the opening `(` already consumed by the caller (depth starts at
-        # 1, not 0, for the same reason).
-        #
-        # @param expr [String] the source text to scan
-        # @param start [Integer] the index just past the already-consumed
-        #   opening `(`
-        # @return [Integer, nil] the index of the matching `)`, or `nil` if
-        #   `expr` has no balanced close from `start` onward
         def matching_paren(expr, start)
           depth = 1
           quote = nil
@@ -883,32 +414,7 @@ module Hecks
           nil
         end
 
-        # Both operands are coerced to a real Integer/Float before the
-        # zero-check, and the check reads the coerced divisor — not the
-        # raw `divisor_value` (which might not even respond to `.zero?`,
-        # a String for instance) and not a `.to_i`-truncated stand-in for
-        # it either. The old order checked a truncated `divisor.to_i`
-        # after already validating the untruncated value wasn't zero, so
-        # a divisor merely small (`0.3`, truncating to `0`) sailed past
-        # the guard and then blew up `Integer#%` with a raw
-        # `ZeroDivisionError` the moment it reached zero anyway.
-        #
-        # The modulo itself is plain `%` on the coerced values, matching
-        # `add`'s own no-truncation precedent just above — Ruby's native
-        # `%` already handles every Integer/Float combination correctly
-        # (promoting to Float when either side is one), so rounding both
-        # operands down to Integer first was pure data loss with no
-        # purpose: `7.5.modulo(2.5)` silently became `7 % 2` (`1`)
-        # instead of the real `0.0`.
-        #
-        # @param receiver_value [Object] the already-interpreted receiver
-        #   value
-        # @param divisor_value [Object] the already-interpreted divisor
-        #   value
-        # @return [Integer, Float] `receiver % divisor`, on the coerced
-        #   numeric operands
-        # @raise [EvaluationError] if either operand is not numeric, or the
-        #   coerced divisor is zero
+        # The zero-check reads the coerced divisor, not the raw value or a `to_i` truncation.
         def apply_modulo(receiver_value, divisor_value)
           receiver = require_number(receiver_value, "modulo")
           divisor  = require_number(divisor_value, "modulo")
@@ -917,20 +423,6 @@ module Hecks
           receiver % divisor
         end
 
-        # Resolves a `Lookup` node's dotted path against `attrs` (checked
-        # first) and `state`, unwrapping a single-field value object's
-        # result to its own scalar.
-        #
-        # @param expr [String] the dotted (or bare) attribute path, such as
-        #   `"customer.status"`
-        # @param state [Hash{Symbol => Object}] the stored attribute values
-        #   the path's root name may resolve against
-        # @param attrs [Hash{Symbol => Object}] the call's own argument
-        #   values, checked before `state`
-        # @return [Object] the resolved value, unwrapped by `unwrap_scalar`
-        # @raise [EvaluationError] if the path's root name is in neither
-        #   `attrs` nor `state`, or a later segment cannot be read from the
-        #   value it navigates onto
         def lookup(expr, state, attrs)
           return unwrap_scalar(fetch(expr, state, attrs)) unless expr.include?(".")
 
@@ -938,25 +430,8 @@ module Hecks
           unwrap_scalar(walk_path(fetch(head, state, attrs), rest))
         end
 
-        # Walks a list of dotted segments through an already-resolved
-        # Hash-like value — extracted from `lookup`'s own reduce so
-        # `found_of` (the `Find` node's own path projection) can walk a
-        # `.find { ... }`-produced element the identical way `lookup`
-        # walks a plain attribute path, rather than duplicating the
-        # symbol-or-string key step twice in this file. `key?` decides
-        # which spelling answers — a bare `||` between the two would
-        # treat a genuinely-held `false` the same as an absent key and
-        # fall through to the other spelling, landing on `nil`.
-        #
-        # @param value [Object] the already-resolved starting value; `nil`
-        #   once any segment lands on a value that does not respond to
-        #   `#[]`
-        # @param segments [Array<String>] the dotted path's remaining
-        #   segments, in order
-        # @return [Object, nil] the value reached by walking every segment,
-        #   or `nil` if a segment lands on a value with no `#[]`
-        # @raise [EvaluationError] if a segment cannot be read from an
-        #   Array-like value (a non-Integer/Range index)
+        # Walks dotted segments through a Hash-like value. `key?` picks the symbol or string
+        # spelling so a held `false` is not mistaken for an absent key.
         def walk_path(value, segments)
           segments.reduce(value) do |current, segment|
             break nil unless current.respond_to?(:[])
@@ -968,15 +443,7 @@ module Hecks
               begin
                 current[segment]
               rescue TypeError
-                # M9 (docs/audits/2026-08-10-main-bug-audit.md): a dotted
-                # path can walk onto an Array (e.g. the result of `.split`,
-                # or a `list_of` attribute) — Array#[] demands an
-                # Integer/Range and raises a raw TypeError for a String
-                # segment ("no implicit conversion of String into
-                # Integer"). This rescue catches it and re-raises as this
-                # sublanguage's own refusal ("this predicate doesn't apply
-                # here"), rather than letting the raw TypeError cross this
-                # sublanguage's own refusal boundary and crash the runtime.
+                # `Array#[]` raises a raw TypeError for a String segment; refuse it instead.
                 raise EvaluationError,
                       "cannot read #{segment.inspect} from #{describe(current)}"
               end
@@ -984,64 +451,9 @@ module Hecks
           end
         end
 
-        # Unwraps a single-field value object to its own scalar, so
-        # `field == "literal"` -- vendored addition, not (yet) upstream
-        # hecks (migration plan task 8): the third-most pervasive
-        # dispatch-time gap this pass found, same family as `.match?`/
-        # `.present?` above -- a lookup of a single-field
-        # scalar-convenience value object (the exact shape `Value.
-        # from_identifier`/`Value::Coercion#fields_for`'s own single-
-        # field auto-unwrap already treats as "this VO IS its scalar"
-        # everywhere else in this runtime) came back as the `Value`
-        # wrapper itself, never unwrapped for reading -- so `Value#==`
-        # (which only ever equals another `Value` instance) silently
-        # refused every `guarantees "..." do status == "active" end` /
-        # `expects "..." do trash_day.present? end`-shaped bare
-        # comparison against a raw literal. Confirmed corpus-wide, not
-        # one file's mistake: bin-buddy alone has this exact `field ==
-        # "literal"` shape in plan.bluebook, service_task.bluebook,
-        # route.bluebook, and subscription.bluebook, all equally silent
-        # until a real dispatch (never validate) exercised the
-        # predicate.
-        #
-        # Unwraps both the bare (undotted) case and a dotted lookup's own
-        # terminal value: a dotted lookup that navigates through an
-        # entity/list element to a nested field (`leg.voyage`, where
-        # `voyage` is itself a single-field VO) lands on the same
-        # unwrapped-`Value` shape a bare lookup does, and hits the
-        # identical silent `Value#==` failure without the same
-        # "this VO IS its scalar" treatment — only the intermediate hops
-        # need raw `#[]` addressing to keep navigating. `unwrap_scalar` is
-        # idempotent on an already-raw scalar (a String/Integer doesn't
-        # respond to `#to_h`), so this is safe for `field.value`-shaped
-        # dotted lookups too — they already return a raw scalar and stay
-        # unaffected.
-        #
-        # Gated on the sole attribute's *count*, never its *name*: gating
-        # on a literal `:value` key would be a lie of omission for
-        # `Money{amount}` and every other single-field value object whose
-        # author picked a domain name for the field — the same
-        # "this VO IS its scalar" reading
-        # ([[feedback_name_the_scalar_field]],
-        # `Behaviour::ValueObject#sole_attribute`) applies regardless of
-        # what the sole field happens to be called, and a name gate would
-        # make a bare `balance > 0` work for a `Balance{value}` while
-        # silently comparing a whole VO for a `Balance{amount}`. A
-        # declared `Runtime::Value` reads its own `sole_attribute` (the
-        # declaration's answer, not the stored hash's); any other
-        # to_h-able (a Struct, a bespoke wrapper with no declaration to
-        # consult) keeps the `{value: X}`-only unwrap, so nothing that
-        # never was a value object gains a surprise unwrapping.
-        # `rust/src/kernel/json.rs`'s `impl Fielded for Json` mirrors the
-        # count-only reading on the Rust side — change them in lockstep
-        # or rust_conformance diverges.
-        #
-        # @param value [Object] a resolved lookup or path-walk result
-        # @return [Object] `value` itself if it is a Hash, Array, or has no
-        #   `#to_h`; a declared `Runtime::Value`'s sole attribute's own
-        #   value, read via `sole.name`, if it has exactly one attribute;
-        #   `value[:value]` for any other to_h-able with exactly one key
-        #   named `:value`; `value` unchanged otherwise
+        # Unwraps a single-field value object to its scalar so `field == "literal"` works.
+        # Gated on the field count, not its name. Mirrors `impl Fielded for Json` in
+        # rust/src/kernel/json.rs; change both together.
         def unwrap_scalar(value)
           return value unless value.respond_to?(:to_h) && !value.is_a?(Hash) && !value.is_a?(Array)
 
@@ -1054,17 +466,6 @@ module Hecks
           hash.size == 1 && hash.key?(:value) ? hash[:value] : value
         end
 
-        # Resolves a single unqualified name — `attrs` first, `state`
-        # second.
-        #
-        # @param name [String, Symbol] the attribute or argument name
-        # @param state [Hash{Symbol => Object}, #[]] the stored attribute
-        #   values
-        # @param attrs [Hash{Symbol => Object}] the call's own argument
-        #   values, checked first
-        # @return [Object] the value held under `name`
-        # @raise [EvaluationError] if `name` is in neither `attrs` nor
-        #   `state`
         def fetch(name, state, attrs)
           key = name.to_sym
           return attrs[key] if attrs.key?(key)
@@ -1073,45 +474,21 @@ module Hecks
           raise EvaluationError, "cannot resolve #{name.inspect} — no such attribute or argument"
         end
 
-        # Reports whether `state` holds `key`, duck-typed for a `state`
-        # that does not respond to `:key?`.
-        #
-        # @param state [Hash{Symbol => Object}, #[]] the stored attribute
-        #   values
-        # @param key [Symbol] the attribute name to look for
-        # @return [Boolean] `state.key?(key)` when `state` responds to
-        #   `:key?`; otherwise whether `state[key]` is non-nil
         def known?(state, key)
           return state.key?(key) if state.respond_to?(:key?)
 
           !state[key].nil?
         end
 
-        # Returns `value` if it is already numeric, or `nil` if it is not.
-        #
-        # @param value [Object] the value to check
-        # @return [Integer, Float, nil] `value` unchanged if it is an
-        #   Integer or Float, otherwise `nil`
         def numeric(value)
           value if value.is_a?(Integer) || value.is_a?(Float)
         end
 
-        # Coerces `value` to a number or refuses it.
-        #
-        # @param value [Object] the value to check
-        # @param operation [String] the operation name, for the refusal
-        #   message
-        # @return [Integer, Float] `value` unchanged
-        # @raise [EvaluationError] if `value` is not an Integer or Float
         def require_number(value, operation)
           numeric(value) ||
             raise(EvaluationError, "#{operation} expects a number, got #{describe(value)}")
         end
 
-        # Renders `value` the way it should read inside a refusal message.
-        #
-        # @param value [Object] the value to render
-        # @return [String] `Rendering.describe(value)`
         def describe(value) = Rendering.describe(value)
       end
     end