hecks 1.3.0 → 1.5.0

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

@@ -4,17 +4,19 @@ require_relative "resolver"
 module Hecks
   module Bluebook
     module Expression
-      # ── AST → JSON — walks the REAL Evaluator/Resolver AST (the same
-      # objects a live dispatch parses `given`/`ensures`/invariant text
-      # into — see docs/implemented/guides/running-a-runtime.md's "The
-      # expression grammar") and emits plain, JSON-serializable Ruby
-      # Hashes, tagged by `"op"`.
+      # Walks the real Evaluator/Resolver AST (the same objects a live
+      # dispatch parses `given`/`ensures`/invariant text into — see
+      # docs/implemented/guides/running-a-runtime.md's "The expression
+      # grammar") and emits plain, JSON-serializable Ruby Hashes, tagged
+      # by `"op"`.
       #
-      # THE SAME TWO-METHOD WALK `rust/project/expr_emitter.rb`'s own
-      # `emit_bool`/`emit_resolver` already do, over the SAME AST — that
-      # file's own methods build RUST SOURCE-CODE STRINGS for `rust/
+      # ## Why this exists beside `rust/project/expr_emitter.rb`
+      #
+      # The same two-method walk `rust/project/expr_emitter.rb`'s own
+      # `emit_bool`/`emit_resolver` already do, over the same AST — that
+      # file's own methods build Rust source-code strings for `rust/
       # project`'s codegen (`rust/src/kernel::expr::Expr` literals, baked
-      # into a generated domain's own compiled binary); this builds DATA
+      # into a generated domain's own compiled binary); this builds data
       # instead, for a genuinely different consumer with a genuinely
       # different constraint: `rust/host` can never link the `rust`
       # (kernel) crate at all (a real, load-bearing build constraint —
@@ -22,41 +24,44 @@ module Hecks
       # path dependency would statically bake every domain's generated
       # dispatch code into every Lambda binary), so a value object's own
       # `invariant` predicate has to travel as something `rust/host` can
-      # deserialize and interpret itself, at RUNTIME, from `ir.json` — the
+      # deserialize and interpret itself, at runtime, from `ir.json` — the
       # exact same relationship `rust/project`'s own `Expr` literals
       # already have to the compiled kernel, one layer further out.
       #
-      # LIVES IN CORE `lib/hecks`, NOT `rust/project/` — `rust/project.rb`
-      # is a separate, downstream toolchain
+      # ## Why it lives in core `lib/hecks`, not `rust/project/`
+      #
+      # `rust/project.rb` is a separate, downstream toolchain
       # (`lib/hecks/projector.rb`'s own header: "a whole separate Ruby
       # program"), never `require`d by core `lib/hecks/bluebook/*.rb`
       # files (confirmed: no core file does). `value_object.rb`'s own
-      # `invariants:` IR emission needs this for EVERY domain's ordinary
+      # `invariants:` IR emission needs this for every domain's ordinary
       # `to_h`/`ir.json` export — golden fixtures, `hecks-parse`'s parity
       # comparisons, and any deploy artifact, not only a `bin/project_rust`
       # run — so it belongs beside `Evaluator`/`Resolver` themselves, not
       # bolted onto a tool that only sometimes runs.
       #
-      # COMPLETE, not corpus-scoped: every node this grammar admits gets
-      # a real arm, the identical "raise, don't silently drop" discipline
-      # `expr_emitter.rb`'s own `emit_bool`/`emit_resolver` already hold
-      # to — even though, as of this writing, no real corpus VALUE OBJECT
-      # invariant exercises `Include`/`Modulo`/`BlockPredicate`/`Find`/
-      # `Array`/`MatchesRegex`/`Presence`/`Assignment`/`Split`/`StartsWith`/
-      # `EndsWith`/`First`/`Last` (only `given`/`ensures` clauses do, elsewhere in
-      # the corpus — a different consumer of this same grammar).
-      # `rust/host/src/expr_json.rs`'s own header names exactly which of
-      # these its interpreter evaluates for real today versus refuses
-      # cleanly — a narrower, deliberate, documented boundary on the
-      # INTERPRETING side, not on this EMITTING side: an author is free
-      # to write ANY real expression in a value object's own `invariant`,
-      # and this always emits it faithfully; whether `rust/host` can yet
-      # CHECK it at mint time is that file's own question to answer, not
-      # this one's to pre-empt by refusing to even try.
+      # ## Complete, not corpus-scoped
+      #
+      # Every node this grammar admits gets a real arm, the identical
+      # "raise, don't silently drop" discipline `expr_emitter.rb`'s own
+      # `emit_bool`/`emit_resolver` already hold to — even though, as of
+      # this writing, no real corpus value object invariant exercises
+      # `Include`/`Modulo`/`BlockPredicate`/`Find`/`Array`/`MatchesRegex`/
+      # `Presence`/`Assignment`/`Split`/`StartsWith`/`EndsWith`/`First`/
+      # `Last` (only `given`/`ensures` clauses do, elsewhere in the corpus
+      # — a different consumer of this same grammar). `rust/host/src/
+      # expr_json.rs`'s own header names exactly which of these its
+      # interpreter evaluates for real today versus refuses cleanly — a
+      # narrower, deliberate, documented boundary on the interpreting
+      # side, not on this emitting side: an author is free to write any
+      # real expression in a value object's own `invariant`, and this
+      # always emits it faithfully; whether `rust/host` can yet check it
+      # at mint time is that file's own question to answer, not this
+      # one's to pre-empt by refusing to even try.
       module AstJson
         module_function
 
-        # THE CLOSED OP ROSTER — every `"op"` tag the walkers below can
+        # **The closed op roster** — every `"op"` tag the walkers below can
         # emit, pinned so a reader (or a spec) can refuse a tag it does
         # not know instead of guessing. A new node kind is a new entry
         # here, a new arm below, and a new arm in every reader.
@@ -68,16 +73,26 @@ module Hecks
           matches_regex presence assignment split starts_with ends_with
         ].freeze
 
-        # ONE RULE ROW, THE WAY EVERY RULE SITE EMITS IT — description and
+        # One rule row, the way every rule site emits it — description and
         # canonical text (what every reader has always had) plus the
         # structured form, derived from the same text. `ast` is a pure
         # function of `canonical`: the IR carries both so a reader that
         # only displays keeps the text, and a reader that evaluates never
         # re-parses it.
+        #
+        # @param rule [Bluebook::Given, Bluebook::Invariant] the rule to
+        #   render; `rule.ast` is used when already computed, otherwise
+        #   `rule.canonical` is parsed and emitted fresh
+        # @return [Hash{Symbol => Object}] `:description` (`String`),
+        #   `:canonical` (`String`), and `:ast` (`Hash`, the JSON AST)
         def rule_row(rule)
           { description: rule.description, canonical: rule.canonical, ast: rule.ast || emit_predicate(rule.canonical) }
         end
 
+        # Parses `canonical` and emits its JSON AST in one step.
+        #
+        # @param canonical [String] a canonical predicate source string
+        # @return [Hash] the JSON-shaped boolean AST, tagged by `"op"`
         def emit_predicate(canonical)
           emit_bool(Evaluator.parse(canonical))
         end
@@ -89,6 +104,17 @@ module Hecks
         # engine reading it is a defect in the bluebook, refused at build.
         # Walks the emitted AST, so every rule site (givens, ensures,
         # invariants, preconditions, a policy's where) gets the one check.
+        #
+        # @param ast [Hash] a JSON AST node, as emitted by `emit_predicate`
+        #   or `emit_bool`
+        # @param owner [String] the declaring bluebook's name, for the
+        #   refusal message
+        # @param word [String] the rule's own kind and description
+        #   (such as `"given \"total is positive\""`), for the refusal
+        #   message
+        # @return [Hash] `ast`, unchanged
+        # @raise [Bluebook::DSL::Malformed] if any `matches_regex` node's
+        #   pattern uses a construct `PatternSubset` does not admit
         def refuse_unshared_patterns!(ast, owner:, word:)
           return ast if Hecks::Bluebook::MetaValidator.shadow_parsing? # frozen era text is history
 
@@ -107,6 +133,11 @@ module Hecks
 
         # Every name a rule resolves at its root — the first segment of
         # each `lookup` path, unique, in first-seen order.
+        #
+        # @param ast [Hash] a JSON AST node, as emitted by `emit_predicate`
+        #   or `emit_bool`
+        # @return [Array<String>] each `lookup` node's root name, unique,
+        #   in first-seen order
         def lookup_heads(ast)
           heads = []
           each_node(ast) do |node|
@@ -115,6 +146,13 @@ module Hecks
           heads.uniq
         end
 
+        # Visits `node` and every Hash node nested inside it, depth-first.
+        #
+        # @param node [Hash, Array, Object] a JSON AST node, or an Array or
+        #   scalar value found while walking one; a scalar is a silent no-op
+        # @yieldparam node [Hash] each Hash node reached, including `node`
+        #   itself
+        # @return [void]
         def each_node(node, &block)
           case node
           when ::Hash
@@ -125,6 +163,17 @@ module Hecks
           end
         end
 
+        # Emits the JSON form of one boolean-position Evaluator node.
+        #
+        # @param node [Bluebook::Expression::Evaluator::Or,
+        #   Bluebook::Expression::Evaluator::And,
+        #   Bluebook::Expression::Evaluator::Not,
+        #   Bluebook::Expression::Evaluator::Compare,
+        #   Bluebook::Expression::Evaluator::Include,
+        #   Bluebook::Expression::Evaluator::Resolve] the boolean-position
+        #   AST node to emit
+        # @return [Hash] the JSON AST for `node`, tagged by `"op"`
+        # @raise [RuntimeError] if `node` is not one of the handled classes
         def emit_bool(node)
           case node
           when Evaluator::Or  then { "op" => "or", "left" => emit_bool(node.left), "right" => emit_bool(node.right) }
@@ -143,21 +192,37 @@ module Hecks
           end
         end
 
+        # Emits the JSON form of one comparison operator.
+        #
+        # @param comparator [Bluebook::Expression::Evaluator::Operator] the
+        #   operator to emit
+        # @return [Hash{String => Boolean}] `"less_than"`, `"equal"`, and
+        #   `"negated"`, exactly as `comparator` carries them
         def emit_comparison(comparator)
           { "less_than" => comparator.compares_less_than, "equal" => comparator.compares_equal, "negated" => comparator.negated }
         end
 
         # The JSON-target sibling of `expr_emitter.rb`'s own
         # `emit_include` — see that method's own comment for the full
-        # reasoning (a LITERAL array haystack has no `Expr::Include`-
-        # representable shape on EITHER target, kernel or host, so both
-        # rewrite it identically into an OR-of-equalities at emission
+        # reasoning (a literal array haystack has no `Expr::Include`-
+        # representable shape on either target, kernel or host, so both
+        # rewrite it identically into an or-of-equalities at emission
         # time rather than carrying a shape neither interpreter could
         # evaluate). A non-literal haystack still emits `include`
         # unchanged.
         EQ = Evaluator::OPERATORS.find { |op| op.symbol == "==" }
         private_constant :EQ
 
+        # Emits the JSON form of one `include` node.
+        #
+        # @param node [Bluebook::Expression::Evaluator::Include] the
+        #   `include` node to emit
+        # @return [Hash] the JSON AST: `{"op" => "include", ...}` for a
+        #   non-literal haystack, `{"op" => "bool", "value" => false}` for
+        #   an empty literal array haystack, or an `"or"`-of-`"compare"`
+        #   tree of equalities for a non-empty literal array haystack
+        # @raise [RuntimeError] if `node.haystack`, `node.needle`, or one of
+        #   the haystack's literal elements is an unhandled resolver node
         def emit_include(node)
           return { "op" => "include", "haystack" => emit_resolver(node.haystack), "needle" => emit_resolver(node.needle) } \
             unless node.haystack.is_a?(Resolver::ArrayLiteral)
@@ -172,10 +237,37 @@ module Hecks
         end
 
         # One case arm per Resolver node type — the class header above is
-        # explicit that this dispatch must stay COMPLETE and in one place
+        # explicit that this dispatch must stay complete and in one place
         # ("every node this grammar admits gets a real arm"); splitting it
         # into several methods would hide whether the set is still
         # exhaustive instead of making that visible at a glance.
+        #
+        # @param node [Bluebook::Expression::Resolver::IntegerLiteral,
+        #   Bluebook::Expression::Resolver::FloatLiteral,
+        #   Bluebook::Expression::Resolver::StringLiteral,
+        #   Bluebook::Expression::Resolver::BoolLiteral,
+        #   Bluebook::Expression::Resolver::NilLiteral,
+        #   Bluebook::Expression::Resolver::Lookup,
+        #   Bluebook::Expression::Resolver::Addition,
+        #   Bluebook::Expression::Resolver::SignTest,
+        #   Bluebook::Expression::Resolver::Empty,
+        #   Bluebook::Expression::Resolver::ToS,
+        #   Bluebook::Expression::Resolver::Modulo,
+        #   Bluebook::Expression::Resolver::Size,
+        #   Bluebook::Expression::Resolver::BlockPredicate,
+        #   Bluebook::Expression::Resolver::Find,
+        #   Bluebook::Expression::Resolver::ArrayLiteral,
+        #   Bluebook::Expression::Resolver::MatchesRegex,
+        #   Bluebook::Expression::Resolver::Presence,
+        #   Bluebook::Expression::Resolver::Assignment,
+        #   Bluebook::Expression::Resolver::Split,
+        #   Bluebook::Expression::Resolver::StartsWith,
+        #   Bluebook::Expression::Resolver::EndsWith,
+        #   Bluebook::Expression::Resolver::First,
+        #   Bluebook::Expression::Resolver::Last] the value-position AST
+        #   node to emit
+        # @return [Hash] the JSON AST for `node`, tagged by `"op"`
+        # @raise [RuntimeError] if `node` is not one of the handled classes
         # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
         def emit_resolver(node)
           case node
@@ -184,7 +276,7 @@ module Hecks
           when Resolver::StringLiteral  then { "op" => "str", "value" => node.value }
           when Resolver::BoolLiteral    then { "op" => "bool", "value" => node.value }
           when Resolver::NilLiteral     then { "op" => "nil" }
-          # `path` is the SAME shape `find.path` already has — segments, not
+          # `path` is the same shape `find.path` already has — segments, not
           # a dotted string a reader would have to split by its own rule.
           when Resolver::Lookup         then { "op" => "lookup", "path" => node.path.split(".") }
           when Resolver::Addition       then { "op" => "add", "left" => emit_resolver(node.left), "right" => emit_resolver(node.right) }

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

@@ -4,8 +4,8 @@ require_relative "resolver"
 module Hecks
   module Bluebook
     module Expression
-      # THE INVERSE OF `AstJson` — reads the `"op"`-tagged JSON a rule row
-      # carries as `ast` back into the SAME `Evaluator`/`Resolver` node
+      # The inverse of `AstJson` — reads the `"op"`-tagged JSON a rule row
+      # carries as `ast` back into the same `Evaluator`/`Resolver` node
       # Structs `Evaluator.parse` builds from `canonical`. This is how the
       # runtime evaluates a rule without re-parsing its text: the one
       # parse happened at DSL-build time, behind `AstJson`; dispatch walks
@@ -19,15 +19,26 @@ module Hecks
       # the spec proved the round trip first, then the runtime adopted it.
       #
       # One deliberate asymmetry, inherited: `AstJson` rewrites a
-      # LITERAL-array `.include?` into an OR of equalities (see
+      # literal-array `.include?` into an or of equalities (see
       # `emit_include`), so reading never produces an `Include` over an
       # `ArrayLiteral`. Evaluation is unchanged by that rewrite, which is
       # exactly what the equivalence spec pins.
       module AstReader
         module_function
 
+        # Reads a whole predicate's own `"op"`-tagged JSON back into its AST.
+        #
+        # @param json [Hash{String => Object}] the `"op"`-tagged JSON a rule row's own
+        #   `ast` carries
+        # @return [Evaluator::Or, Evaluator::And, Evaluator::Not, Evaluator::Compare,
+        #   Evaluator::Include, Evaluator::Resolve] the boolean/comparison AST node
         def read_predicate(json) = read_bool(json)
 
+        # Reads one boolean/comparison node, recursing into its own children.
+        #
+        # @param json [Hash{String => Object}] the `"op"`-tagged JSON for one node
+        # @return [Evaluator::Or, Evaluator::And, Evaluator::Not, Evaluator::Compare,
+        #   Evaluator::Include, Evaluator::Resolve] the boolean/comparison AST node
         def read_bool(json)
           case json.fetch("op")
           when "or"      then Evaluator::Or.new(left: read_bool(json["left"]), right: read_bool(json["right"]))
@@ -46,6 +57,10 @@ module Hecks
         # `Operator` carrying that exact triple is the one `parse` would
         # have chosen, because the roster (`expression/projection.json`)
         # holds one symbol per triple.
+        #
+        # @param cmp [Hash{String => Boolean}] `{"less_than"=>, "equal"=>, "negated"=>}`
+        # @return [Evaluator::Operator] the operator carrying that exact triple
+        # @raise [RuntimeError] if no operator in `Evaluator::OPERATORS` has that triple
         def operator(cmp)
           Evaluator::OPERATORS.find do |op|
             op.compares_less_than == cmp.fetch("less_than") &&
@@ -54,6 +69,15 @@ module Hecks
           end or raise "no comparison operator has the triple #{cmp.inspect}"
         end
 
+        # Reads one dotted/arithmetic leaf node, recursing into its own children.
+        #
+        # @param json [Hash{String => Object}] the `"op"`-tagged JSON for one leaf node
+        # @return [Object] a `Resolver` AST node — one of `IntegerLiteral`, `FloatLiteral`,
+        #   `StringLiteral`, `BoolLiteral`, `NilLiteral`, `ArrayLiteral`, `Lookup`,
+        #   `Addition`, `SignTest`, `Empty`, `ToS`, `Modulo`, `Size`, `First`, `Last`,
+        #   `BlockPredicate`, `Find`, `MatchesRegex`, `Presence`, `Assignment`, `Split`,
+        #   `StartsWith`, or `EndsWith`
+        # @raise [RuntimeError] if `json["op"]` names no known resolver op
         # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity -- one arm
         # per AstJson op is the point; splitting the case would hide the roster.
         def read_resolver(json)
@@ -98,6 +122,11 @@ module Hecks
         # triple is what evaluates. Recover the spelling from the
         # vocabulary so a rebuilt node refuses with the same message the
         # parsed one would.
+        #
+        # @param operator [Evaluator::Operator] the comparison operator a sign test's own
+        #   triple resolved to
+        # @return [String] the sign test's own vocabulary name, or `operator.symbol` when
+        #   no sign test shares its triple
         def sign_test_name(operator)
           Resolver::SIGN_TEST_OPERATORS.key(operator.symbol) || operator.symbol
         end

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

@@ -4,7 +4,7 @@ require_relative "../../vocabulary"
 module Hecks
   module Bluebook
     module Expression
-      # Rewrites a predicate's SOURCE TEXT into one canonical spelling
+      # Rewrites a predicate's source text into one canonical spelling
       # before it's ever parsed or hashed — collapsing whitespace and
       # folding admitted synonyms (e.g. `.length` → `.size`) via the
       # `RULES` table projected from the grammar chapter, so two byte-
@@ -16,7 +16,7 @@ module Hecks
 
         STRATEGIES = Hecks::Vocabulary.fetch("NormalisationStrategy")
 
-        # READ, NOT RESTATED — the admitted normalisation rules, projected
+        # **Read, not restated** — the admitted normalisation rules, projected
         # from the grammar chapter by bin/expression_projection exactly as
         # the evaluator's operator table is. See Evaluator::PROJECTION for
         # why a projection rather than a boot.
@@ -26,6 +26,13 @@ module Hecks
 
         module_function
 
+        # Returns the admitted normalisation rules as plain Hashes, for
+        # embedding in a bluebook's read-back contract.
+        #
+        # @return [Array<Hash{Symbol => String}>] one hash per rule, in
+        #   declared `position` order, with keys `:strategy`,
+        #   `:source_token`, `:replacement`, `:boundary`, and `:position`
+        #   (stringified)
         def table
           RULES.sort_by(&:position).map do |rule|
             {
@@ -38,10 +45,25 @@ module Hecks
           end
         end
 
+        # Rewrites `source` into its canonical spelling by applying every
+        # admitted `RULES` entry, in declared `position` order.
+        #
+        # @param source [String] the raw predicate source to normalise
+        # @return [String] the canonicalised text, stripped of leading and
+        #   trailing whitespace
         def apply(source)
           RULES.sort_by(&:position).reduce(source.to_s) { |text, rule| step(text, rule) }.strip
         end
 
+        # Applies one normalisation `rule` to `text`, dispatching on the
+        # rule's strategy.
+        #
+        # @param text [String] the source text (or string-literal segment) to
+        #   transform
+        # @param rule [Rule] the normalisation rule to apply
+        # @return [String] `text` after the rule is applied
+        # @raise [ArgumentError] if `rule.strategy` names a strategy this
+        #   method does not implement
         def step(text, rule)
           case rule.strategy
           when "collapse_whitespace" then map_outside_strings(text) { |segment| segment.gsub(/\s+/, " ") }
@@ -51,6 +73,14 @@ module Hecks
           end
         end
 
+        # Substitutes every occurrence of `rule.source_token` in `text` with
+        # `rule.replacement`, honoring the rule's word-boundary setting.
+        #
+        # @param text [String] the source text (or string-literal segment) to
+        #   transform
+        # @param rule [Rule] the `"replace"`-strategy rule supplying the
+        #   token, replacement, and boundary
+        # @return [String] `text` with the substitution applied
         def replace(text, rule)
           map_outside_strings(text) do |segment|
             if rule.boundary == "none"
@@ -61,21 +91,30 @@ module Hecks
           end
         end
 
-        # Applies a normalisation rule to the text OUTSIDE quoted string
-        # literals only, copying every quoted run through byte-for-byte.
-        # Every rule here (collapse_whitespace, the `.length`→`.size` fold)
-        # used to run quote-blind — `"a  b"` collapsed to `"a b"` and
-        # `"a.length"` folded to `"a.size"` just as readily as the real
-        # source outside the quotes, silently rewriting what a predicate
-        # compares a string attribute against, not merely how the
-        # predicate itself is spelled. A canonical string literal's
-        # CONTENTS are data, never syntax to normalise.
+        # Applies the given block to the text outside quoted string literals
+        # only, copying every quoted run through byte-for-byte. Every rule
+        # here (collapse_whitespace, the `.length`→`.size` fold) must stay
+        # quote-aware: run it quote-blind and `"a  b"` collapses to `"a b"`,
+        # `"a.length"` folds to `"a.size"`, just as readily as the real
+        # source outside the quotes — silently rewriting what a predicate
+        # compares a string attribute against, not merely how the predicate
+        # itself is spelled. A canonical string literal's contents are data,
+        # never syntax to normalise.
         #
         # Handles both `"` and `'` delimiters (this grammar's own
         # `Resolver.quoted?` admits either), quote-aware exactly the way
         # `Evaluator.top_level_index`/`Resolver.array_elements` already are
         # elsewhere in this sublanguage. An unterminated quote (malformed
         # input) is passed through raw rather than risk mangling it further.
+        #
+        # @param text [String] the source text to scan for quoted string
+        #   literals
+        # @yieldparam segment [String] a run of `text` outside any quoted
+        #   literal
+        # @yieldreturn [String] the transformed replacement for `segment`
+        # @return [String] `text` with the block applied to every unquoted
+        #   run, and every quoted run (`"`- or `'`-delimited) copied through
+        #   unchanged
         def map_outside_strings(text)
           result = +""
           buffer = +""
@@ -93,9 +132,9 @@ module Hecks
               result << yield(buffer)
               # `char.dup`, not `char.to_s` (a no-op on a String — always
               # returns self, never a copy) and not `+char` either
-              # (`String#+@` only dups a FROZEN receiver; `each_char`'s
+              # (`String#+@` only dups a frozen receiver; `each_char`'s
               # yielded strings aren't frozen, so `+char` is just as
-              # much a no-op here). Without a REAL copy, `buffer` and
+              # much a no-op here). Without a real copy, `buffer` and
               # `quote` alias the same mutable object: the very next
               # `buffer << char` grows `quote` right along with it, so
               # `char == quote` can only ever compare a single character
@@ -103,12 +142,12 @@ module Hecks
               # literal — everything after a predicate's first quoted
               # string silently skipped normalisation for the rest of
               # the text, undetected because passing text through
-              # unnormalised is silent. MASKED by every existing spec
-              # here, which only checks that quoted CONTENTS survive
+              # unnormalised is silent. Masked by every existing spec
+              # here, which only checks that quoted contents survive
               # untouched (the M7 fix this method exists for) — that
               # still holds by accident once the bug makes the "outside"
               # branch unreachable. Found live: a multi-line `given`/
-              # `ensures` block whose ONLY quoted literal closes before a
+              # `ensures` block whose only quoted literal closes before a
               # later line — the newline and that later line's own
               # indentation went uncollapsed, diverging from
               # `hecks-parse`'s own (correct) single-space join.