hecks 1.3.0 → 1.5.0

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

@@ -20,14 +20,12 @@ module Hecks
         SIGN_TESTS = Hecks::Vocabulary.fetch("SignTest")
 
         # Which Comparison operator each sign test is sugar for, against the
-        # literal 0 — declared the same way in Vocabulary::SignTest's
-        # compares_via (language/bluebook/vocabulary.bluebook) ; spec/vocabulary_conformance_spec
-        # holds the two tables equal.
-        SIGN_TEST_OPERATORS = {
-          "positive?" => ">",
-          "negative?" => "<",
-          "zero?"     => "=="
-        }.freeze
+        # literal 0 — Vocabulary::SignTest's own compares_via
+        # (language/bluebook/vocabulary.bluebook), read off the generated
+        # table rather than typed a second time.
+        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
@@ -40,7 +38,7 @@ module Hecks
         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
+        # 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
@@ -66,18 +64,18 @@ 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
+        # 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
+        # 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)
+        # 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
+        # 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
+        # (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
@@ -88,13 +86,13 @@ module Hecks
         #
         # `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
+        # 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:
+        # 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
+        # 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,
@@ -118,13 +116,13 @@ module Hecks
         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
+        # 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),
+        # 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
+        # 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
@@ -144,7 +142,7 @@ module Hecks
         # `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
+        # 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
@@ -190,10 +188,10 @@ module Hecks
         # 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
-        # identical `TypeError: no implicit conversion of Symbol into
-        # Integer` shape `.split`/`.all?` used to, confirmed live via a
-        # real dispatch (not validate), not inferred. Two separate node
-        # types rather than one `mode:`-keyed struct (the `BlockPredicate`/
+        # 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
@@ -208,18 +206,44 @@ module Hecks
 
         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.
+        #
+        # @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
         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
+        # 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.
+        # precedence order this method's own line-by-line sequence is.
+        #
+        # @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
         # rubocop:disable-next Metrics/AbcSize
         # rubocop:disable-next Metrics/CyclomaticComplexity
         # rubocop:disable-next Metrics/MethodLength
@@ -289,6 +313,13 @@ 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)
@@ -299,10 +330,25 @@ module Hecks
         # `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
+        # 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.
+        #
+        # @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
         # rubocop:disable-next Metrics/AbcSize
         # rubocop:disable-next Metrics/CyclomaticComplexity
         # rubocop:disable-next Metrics/MethodLength
@@ -365,11 +411,16 @@ module Hecks
 
         # `.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"}`,
+        # 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
 
@@ -389,11 +440,23 @@ module Hecks
         # `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
+        # 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
@@ -410,7 +473,7 @@ 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
+          # 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
@@ -420,9 +483,14 @@ module Hecks
         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,
+        # 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?("]")
 
@@ -455,9 +523,9 @@ module Hecks
           elements.reject(&:empty?)
         end
 
-        # BRACES COUNT TOWARD DEPTH, exactly as parens do — a `+` inside a
+        # 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`,
+        # 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
@@ -468,6 +536,11 @@ module Hecks
         # 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
         def split_addition(expr)
           depth = 0
           quote = nil
@@ -481,12 +554,13 @@ module Hecks
             # 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 now, not only as
-            # `.include?`'s own haystack, so an array element containing
-            # its own top-level `+` (`[0, 0 + 0]`) used to read as THIS
-            # expression's own addition split point -- the whole
-            # receiver before `.all?`/`.any?`/etc. torn in half before
-            # `parse_block_opener` ever saw it as one atomic leaf.
+            # 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.
             elsif ["(", "{", "["].include?(char)
               depth += 1
             elsif [")", "}", "]"].include?(char)
@@ -505,6 +579,16 @@ module Hecks
         # it. A Float sum that is not finite is the same fault (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")
@@ -519,6 +603,12 @@ 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
 
@@ -532,67 +622,111 @@ module Hecks
         # which admit the same set for the same reason.
         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
 
-        # `.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).
+        # 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
 
-        # `.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.
+        # 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
 
-        # `.first` -- see the `First` struct's own comment above.
-        # `last_of` with the one method swapped, same duck-typed
-        # reasoning.
+        # 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)
 
@@ -604,6 +738,13 @@ module Hecks
         # holds this equal to the language.
         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
@@ -614,6 +755,16 @@ 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}"
@@ -622,6 +773,14 @@ 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
@@ -629,50 +788,58 @@ module Hecks
           Evaluator.apply(node.operator, number, 0)
         end
 
-        # FOUND LIVE via the type-directed bounded-exhaustive expression
+        # 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
+        # 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
+        # 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
+        # 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
+        # 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
+        # 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
+        # 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
+        # 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
+        # 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
+        # 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
         def match_call(expr, marker)
           start = 0
           while (index = expr.index(marker, start))
@@ -684,10 +851,17 @@ module Hecks
           nil
         end
 
-        # `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).
+        # 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
@@ -709,12 +883,12 @@ 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
+        # 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
+        # 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.
@@ -726,6 +900,15 @@ module Hecks
         # 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
         def apply_modulo(receiver_value, divisor_value)
           receiver = require_number(receiver_value, "modulo")
           divisor  = require_number(divisor_value, "modulo")
@@ -734,6 +917,20 @@ 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?(".")
 
@@ -750,6 +947,16 @@ module Hecks
         # 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)
         def walk_path(value, segments)
           segments.reduce(value) do |current, segment|
             break nil unless current.respond_to?(:[])
@@ -766,10 +973,10 @@ module Hecks
                 # 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"), which used to cross straight past this
-                # sublanguage's own refusal boundary and crash the
-                # runtime instead of reading as "this predicate doesn't
-                # apply here."
+                # 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.
                 raise EvaluationError,
                       "cannot read #{segment.inspect} from #{describe(current)}"
               end
@@ -777,6 +984,7 @@ 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?`/
@@ -785,7 +993,7 @@ module Hecks
         # 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#==`
+        # 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
@@ -794,48 +1002,46 @@ module Hecks
         # "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. Scoped narrowly to the single-field `{value: X}`
-        # shape only.
-        #
-        # UPDATE 2026-08-18: originally scoped to unwrap ONLY the bare
-        # (undotted) case, on the belief that a dotted lookup only ever
-        # reaches into a VO's OWN field (`field.value`, `field.sub_
-        # field`) and so should keep walking `#[]` untouched. That
-        # belief held for the single-hop case but not for the general
-        # one: a dotted lookup that NAVIGATES THROUGH an entity/list
-        # element to a nested field (`leg.voyage`, where `voyage` is
-        # itself a single-field VO) landed on the very same unwrapped-
-        # `Value` shape the bare case fixed, and hit the identical
-        # silent `Value#==` failure -- comparing it against a raw
-        # literal or another unwrapped VO returned false for everything,
-        # no error. The terminal value of a dotted walk deserves the
-        # same "this VO IS its scalar" treatment as a bare lookup's
-        # result; 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 the existing `field.value`-
-        # shaped dotted lookups too -- they already returned a raw
-        # scalar and are unaffected.
-        # UPDATE (single-element value objects strictly answer `.value`):
-        # the unwrap used to gate on the sole key being literally NAMED
-        # `:value` — correct for the shorthand/closed-set shapes that
-        # motivated it, but 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 the name gate made a bare
-        # `balance > 0` work for a `Balance{value}` while silently
-        # comparing a whole VO for a `Balance{amount}`. Now the COUNT is
-        # the gate, never the name. 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 original
-        # `{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.
+        # 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
         def unwrap_scalar(value)
           return value unless value.respond_to?(:to_h) && !value.is_a?(Hash) && !value.is_a?(Array)
 
@@ -848,6 +1054,17 @@ 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)
@@ -856,21 +1073,45 @@ 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