hecks 1.3.0 → 1.4.0

data/lib/hecks/fuzzing/bounded_exhaustive_expressions.rb

@@ -8,7 +8,7 @@ module Hecks
     # happened to sample," claim is realistically achievable:
     # `Hecks::Bluebook::Expression::{Evaluator,Resolver}`. It's finite-
     # grammar and side-effect-free (Evaluator::PROJECTION/Resolver's own
-    # `interpret` never touch a database, a clock, or randomness), but NOT
+    # `interpret` never touch a database, a clock, or randomness), but not
     # small enough for naive enumeration — ~20 node-producing constructs
     # across two mutually-recursive grammar layers, unbounded recursion
     # through dotted `Lookup` paths, `Addition`, and nested block
@@ -20,8 +20,8 @@ module Hecks
     # `canonical_form.rb` aliasing bug — neither would have been caught by
     # sampling alone, which is the whole reason this phase exists).
     #
-    # TYPE-DIRECTED, not exhaustive-over-strings: this generator only ever
-    # recurses into a sub-expression whose OWN type the surrounding
+    # Type-directed, not exhaustive-over-strings: this generator only ever
+    # recurses into a sub-expression whose own type the surrounding
     # construct actually accepts (never `"x".modulo(true)`) — mirroring,
     # by hand, the same admitted-receiver-class tables `Resolver`'s own
     # `interpret` enforces at runtime (`SizedType`/`ToStringType`/
@@ -36,34 +36,34 @@ module Hecks
     # 3" claim for exactly the sublanguage that already bit this project
     # twice.
     #
-    # WHAT "PROVEN" MEANS HERE, PRECISELY: every expression this generator
-    # produces is well-typed BY CONSTRUCTION (every sub-expression's type
+    # **What "PROVEN" means here, precisely**: every expression this generator
+    # produces is well-typed by construction (every sub-expression's type
     # matches what its parent construct actually accepts, per this file's
     # own TYPE_RULES). Interpreting a well-typed expression must never
-    # raise anything OTHER than `Hecks::Bluebook::Expression::
+    # raise anything other than `Hecks::Bluebook::Expression::
     # EvaluationError` — that class alone is the sublanguage's own real
     # refusal vocabulary (a divisor that happens to be zero, a `Lookup`
     # this run's synthetic state doesn't happen to carry); anything else
     # escaping (a raw `TypeError`/`NoMethodError`/`ZeroDivisionError`) is
     # exactly the crash-signature this whole file's own header comments
     # (resolver.rb, block_predicates.rb) name as the historical bug class
-    # this sublanguage keeps almost-but-not-quite avoiding. This does NOT
-    # prove the interpreter computes the SEMANTICALLY right answer (that
+    # this sublanguage keeps almost-but-not-quite avoiding. This does not
+    # prove the interpreter computes the semantically right answer (that
     # needs a second, independent oracle — out of scope here, exactly the
-    # way rust_conformance_fuzz_spec.rb is the cross-RUNTIME half of this
+    # way rust_conformance_fuzz_spec.rb is the cross-runtime half of this
     # same idea) — only that it never crashes on well-typed input.
     module BoundedExhaustiveExpressions
       module_function
 
-      # `:numeric` deliberately covers BOTH Integer and Float — the
+      # `:numeric` deliberately covers both Integer and Float — the
       # resolver's own `numeric`/`require_number` never distinguish them
       # (resolver.rb) — so a generator that kept them as separate types
       # would be modeling a distinction the grammar itself doesn't make.
       TYPES = %i[numeric string boolean array nil_type].freeze
 
-      # THE PALETTE — deliberately small (this file's own header: "a small
+      # **The palette** — deliberately small (this file's own header: "a small
       # representative literal palette," matching the plan's own `{0, 1,
-      # -1}` example). Widening it doesn't test a different SHAPE of
+      # -1}` example). Widening it doesn't test a different shape of
       # expression, only more values through the same shapes — real
       # boundary-value coverage (Bignum, NaN, empty string, unicode) is
       # PRD 05's job (spec/runtime/numeric_boundary_spec.rb,
@@ -75,18 +75,18 @@ module Hecks
         nil_type: %w[nil].freeze
       }.freeze
 
-      # TWO SYNTHETIC ATTRIBUTES PER TYPE (the plan's own "2-3 fake
+      # Two synthetic attributes per type (the plan's own "2-3 fake
       # attributes per type") — real names are irrelevant to `Resolver
       # .parse` (it never touches state/attrs at all, confirmed directly:
       # only `Lookup#interpret` does) and irrelevant to `interpret` beyond
-      # needing to resolve against WHATEVER synthetic state this file
+      # needing to resolve against whatever synthetic state this file
       # supplies (`synthetic_state`, below) — so any non-colliding,
       # non-suffix-shaped name works. Never named the same as a
       # `BLOCK_PARAM` (below) — `Resolver#fetch`'s own `attrs`-wins-over-
-      # `state` precedence means a block parameter SHADOWS a same-named
+      # `state` precedence means a block parameter shadows a same-named
       # top-level attribute for the span of its own predicate, a real
       # hazard this file sidesteps by construction rather than exercising
-      # it here (a real, cited resolver.rb hazard, not a gap in THIS
+      # it here (a real, cited resolver.rb hazard, not a gap in this
       # generator's own coverage claim).
       SYNTHETIC_ATTRS = {
         numeric: %w[num_a num_b].freeze,
@@ -95,7 +95,7 @@ module Hecks
         array:   %w[arr_num arr_str].freeze
       }.freeze
 
-      # `arr_num`/`arr_str` — ELEMENT type per array attribute, needed so
+      # `arr_num`/`arr_str` — element type per array attribute, needed so
       # a block predicate's own bound parameter (`BLOCK_PARAM`, below) is
       # generated against the right leaf/production set for whatever it's
       # actually bound to.
@@ -105,41 +105,41 @@ module Hecks
 
       MAX_DEPTH = 3
 
-      # `state`/`attrs` — a plain Hash satisfies BOTH (confirmed directly:
+      # `state`/`attrs` — a plain Hash satisfies both (confirmed directly:
       # `Resolver#known?` degrades to a bare index check when `state`
       # doesn't `respond_to?(:key?)`, and `fetch` only ever needs
-      # `attrs.key?`/`attrs[]`.). Split ACROSS both, matching a real
+      # `attrs.key?`/`attrs[]`.). Split across both, matching a real
       # dispatch's own shape (some names come from the record's stored
       # state, some from the command's own args) — not load-bearing for
-      # THIS proof (attrs wins regardless), but keeps the synthetic input
+      # this proof (attrs wins regardless), but keeps the synthetic input
       # closer to what `Admissibility` actually builds, in case anything
       # here is reused for a future deeper check.
       #
-      # THE VO-VS-SCALAR UNWRAP CASE, DELIBERATELY EXERCISED — half of
+      # **The VO-vs-scalar unwrap case, deliberately exercised** — half of
       # `num_a`/`str_a`/`bool_a`/one array attribute's elements are bare
       # scalars, the other half (`num_b`/`str_b`/`bool_b`/the other
       # array's elements) are wrapped `{value: X}` — the single-field
       # Value Object shape `Resolver#unwrap_scalar` auto-collapses.
       # resolver.rb's own most serious historical bug in this file (the
       # "UPDATE 2026-08-18" comment: a dotted walk that landed on an
-      # un-unwrapped VO compared `false` against every literal, SILENTLY,
+      # un-unwrapped VO compared `false` against every literal, silently,
       # never raising) lived exactly at this boundary — a generator that
       # only ever supplied bare scalars would never exercise the code
       # path that bug lived in at all.
-      # `SingleFieldVO` — NOT a plain Hash, deliberately: `Resolver
+      # `SingleFieldVO` — not a plain Hash, deliberately: `Resolver
       # #unwrap_scalar`'s own guard is `value.respond_to?(:to_h) &&
       # !value.is_a?(Hash) && !value.is_a?(Array)` — it exists
       # specifically to collapse a real hydrated `Runtime::Value`
       # instance (which responds to `#to_h` but is never itself a bare
       # Hash) down to its lone scalar field, and just as deliberately
-      # leaves an ACTUAL Hash alone (a genuinely un-hydrated, multi-
+      # leaves an actual Hash alone (a genuinely un-hydrated, multi-
       # field record has no single scalar to collapse to). A first
       # version of this generator's own synthetic state used plain
       # `{value: X}` Hashes to stand in for a single-field VO — which
       # `is_a?(Hash)` is true for, so `unwrap_scalar` correctly left them
-      # WRAPPED, and every VO-typed synthetic attribute then failed
+      # wrapped, and every VO-typed synthetic attribute then failed
       # `Addition`/`Compare`/every scalar-typed operation with "expects a
-      # number, got {\"value\":5}" — a bug in THIS generator's own
+      # number, got {\"value\":5}" — a bug in this generator's own
       # synthetic state, not in `Resolver`, caught only by noticing that
       # `num_b == 5` (`num_b` a plain `{value: 5}` Hash) evaluated to
       # `false` instead of `true` before this fix.
@@ -162,21 +162,21 @@ module Hecks
 
       def synthetic_attrs = {}
 
-      # `leaves(type, depth)` — every TERMINAL (non-recursive) expression
+      # `leaves(type, depth)` — every terminal (non-recursive) expression
       # of `type`: the fixed literal palette plus every synthetic
-      # attribute NAME declared for that type (never their VALUES — this
-      # generates TEXT, the same source a real `given`/`invariant` author
+      # attribute name declared for that type (never their values — this
+      # generates text, the same source a real `given`/`invariant` author
       # would write; `synthetic_state`, above, is what gives those names
       # meaning at `interpret` time).
       def leaves(type)
         (TYPE_LEAVES[type] || []) + (SYNTHETIC_ATTRS[type] || []) + Array(bound_leaves[type])
       end
 
-      # A STACK, not a single slot — a NESTED block predicate (the real
+      # A stack, not a single slot — a nested block predicate (the real
       # corpus already does this two levels deep, roster.bluebook's own
       # `seats.any? { |s| assignments.none? { |a| … } }`) pushes a second
       # bound leaf while the outer one is still active. Both share the
-      # SAME `BLOCK_PARAM` spelling ("el") — real Ruby block-parameter
+      # same `BLOCK_PARAM` spelling ("el") — real Ruby block-parameter
       # shadowing (the inner `el` simply shadows the outer one within its
       # own predicate text), which this generator treats as legal on
       # purpose: `resolver.rb`'s own `interpret_with_element` binds fresh
@@ -196,11 +196,11 @@ module Hecks
       end
 
       # `productions(type, depth)` — every expression of `type` reachable
-      # in AT MOST `depth` recursive steps, MEMOIZED (the same sub-
+      # in at most `depth` recursive steps, memoized (the same sub-
       # expression set is reused at every enclosing recursion, so without
       # memoizing, cost would compound multiplicatively per level instead
       # of additively). `depth` 0 is exactly `leaves(type)`; each
-      # increment adds every construct THIS FILE'S OWN TYPE_RULES (below)
+      # increment adds every construct this file's own TYPE_RULES (below)
       # says can produce `type`, built from `depth - 1` sub-expressions.
       def productions(type, depth)
         cache[[type, depth]] ||= begin
@@ -218,22 +218,22 @@ module Hecks
         when :boolean  then boolean_productions(depth)
         when :array    then array_productions(depth)
         # no recursive producer of nil in this grammar — Find's "not found" is a
-        # runtime OUTCOME, not a distinct construct to render as source text
+        # runtime outcome, not a distinct construct to render as source text
         when :nil_type then []
         else raise ArgumentError, "no production rule for type #{type.inspect}"
         end
       end
 
-      # EVERY internal use of a sub-expression LIST (as opposed to the
+      # Every internal use of a sub-expression list (as opposed to the
       # single final list `productions(type, depth)` returns to its own
       # caller) goes through this, not `productions` directly — the
       # actual thing that made an early version of this generator explode
       # past a million cases by depth 3 wasn't `pairs`' own cross product
-      # (already sampled) but the dozen-plus LINEAR `flat_map`/`map`
+      # (already sampled) but the dozen-plus linear `flat_map`/`map`
       # passes `boolean_productions` alone makes over `str`/`num`/`sub` —
       # each individually harmless, but an unbounded few-thousand-item
-      # list run through a dozen of them, feeding the NEXT depth's own
-      # dozen passes, compounds fast. Bounding every INPUT list (not the
+      # list run through a dozen of them, feeding the next depth's own
+      # dozen passes, compounds fast. Bounding every input list (not the
       # final output) keeps the shape diversity `sample`'s even-spacing
       # already preserves while keeping growth roughly linear in depth
       # instead of combinatorial.
@@ -241,20 +241,20 @@ module Hecks
 
       # NUMERIC ← Addition(numeric, numeric) | Modulo(numeric, numeric) |
       # Size(sized) | First/Last(numeric array). `Size` returns an
-      # Integer for a String OR an Array receiver alike (`SizedType` —
+      # Integer for a String or an Array receiver alike (`SizedType` —
       # `size_of`, resolver.rb) — both sides generated here.
       def numeric_productions(depth)
         sub = bounded(:numeric, depth - 1)
-        # `Modulo`'s own RECEIVER (not its argument — that side already
+        # `Modulo`'s own receiver (not its argument — that side already
         # goes through `Resolver#matching_paren`'s own fresh, self-
         # contained re-parse, confirmed safe for any numeric shape
         # including another `Addition`/`Modulo`) has the identical
         # "`Addition` mis-parsed as a suffix receiver" hazard
         # `resolver_numeric_leaves`'s own comment documents for `.to_s`/
-        # `.positive?` — `Resolver.parse` tries `split_addition` BEFORE
+        # `.positive?` — `Resolver.parse` tries `split_addition` before
         # `match_call`, so `"0 + 0.modulo(1)"` (meant as `(0 + 0)
         # .modulo(1)`) actually parses as `0 + (0.modulo(1))`. Restricted
-        # to `resolver_numeric_leaves` on the RECEIVER side only — the
+        # to `resolver_numeric_leaves` on the receiver side only — the
         # argument stays the full, unrestricted numeric set.
         pairs(sub).map { |a, b| "#{a} + #{b}" } +
           cross(resolver_numeric_leaves(depth - 1), sub).map { |a, b| "#{a}.modulo(#{b})" } +
@@ -263,32 +263,32 @@ module Hecks
           sample(numeric_array_productions(depth - 1)).flat_map { |a| ["#{a}.first", "#{a}.last"] }
       end
 
-      # A "boolean" IN RESOLVER'S OWN SENSE — safe to embed as the
-      # RECEIVER of a trailing Resolver-level suffix (`.to_s`, and
-      # anywhere else a boolean-typed VALUE, as opposed to a boolean-
-      # typed EXPRESSION, is wanted). FOUND LIVE, the same way the
-      # nested-`.modulo` bug was: `Resolver.parse` has NO KNOWLEDGE of
-      # `==`/`<`/`&&`/`||`/leading `!`/`.include?` AT ALL — those are
-      # `Evaluator`'s OWN, entirely separate parsing layer, stripped off
-      # BEFORE anything reaches `Resolver.parse` at all (confirmed
+      # A "boolean" in resolver's own sense — safe to embed as the
+      # receiver of a trailing Resolver-level suffix (`.to_s`, and
+      # anywhere else a boolean-typed value, as opposed to a boolean-
+      # typed expression, is wanted). Found live, the same way the
+      # nested-`.modulo` bug was: `Resolver.parse` has no knowledge of
+      # `==`/`<`/`&&`/`||`/leading `!`/`.include?` at all — those are
+      # `Evaluator`'s own, entirely separate parsing layer, stripped off
+      # before anything reaches `Resolver.parse` at all (confirmed
       # directly: `Resolver.parse("str_b < str_a")` — no `.` anywhere in
       # that text for any suffix regex to anchor on — falls through
       # every leaf regex to the `Lookup` catch-all, exactly like the
-      # nested-modulo bug did). `bounded(:boolean, depth)`'s FULL set
+      # nested-modulo bug did). `bounded(:boolean, depth)`'s full set
       # includes `Compare`/`Include`/`Or`/`And`/`Not` — genuinely boolean-
-      # TYPED at `interpret` time, but `Evaluator`-level SYNTAX, not
+      # typed at `interpret` time, but `Evaluator`-level syntax, not
       # something `Resolver.parse` can ever recognize as a receiver no
       # matter how it's parenthesized (confirmed directly too: `Resolver
       # .parse` never strips parens at all — `"(3)"` alone already fails
-      # to resolve). This is a REAL, PERMANENT boundary of the actual
+      # to resolve). This is a real, permanent boundary of the actual
       # grammar (this whole sublanguage's own two-layer split, not a
       # limitation to work around) — a `given`/`invariant` author simply
       # cannot write `(a < b).to_s` in this language, ever, no matter how
       # they punctuate it. So this generator doesn't either: only
-      # RESOLVER-LEVEL boolean-producing constructs (bare literals/
+      # resolver-level boolean-producing constructs (bare literals/
       # lookups, `SignTest`, `Empty`, `Presence`, `MatchesRegex`,
       # `StartsWith`/`EndsWith`, `BlockPredicate` — every one of them
-      # parsed via a suffix regex INSIDE `Resolver.parse` itself, per
+      # parsed via a suffix regex inside `Resolver.parse` itself, per
       # this generator's own design report) are eligible here.
       def resolver_boolean_leaves(depth)
         leaves(:boolean) +
@@ -302,11 +302,11 @@ module Hecks
           sample(block_predicate_productions(depth))
       end
 
-      # A "numeric" IN RESOLVER'S OWN SENSE — `Addition`'s twin of
+      # A "numeric" in resolver's own sense — `Addition`'s twin of
       # `resolver_boolean_leaves`'s own restriction, found the identical
       # way: `"0 + 0.to_s"` (meant as `(0 + 0).to_s`) actually parses as
       # `0 + (0.to_s)`, because `Resolver.parse` tries `split_addition`
-      # BEFORE `.to_s`'s own suffix regex in its dispatch order — the `+`
+      # before `.to_s`'s own suffix regex in its dispatch order — the `+`
       # "wins" the split before the suffix ever gets a chance to anchor
       # on its own receiver boundary. Confirmed to have zero real-corpus
       # precedent either (`grep`, no `bluebook` file anywhere chains a
@@ -315,7 +315,7 @@ module Hecks
       # a real permanent grammar boundary (`Resolver.parse` never strips
       # parens, confirmed directly, so no amount of punctuation rescues
       # `(a + b).to_s`), not a bug to fix in the resolver for a shape
-      # nothing has ever needed. `Modulo`/`Size`/`First`/`Last` stay IN
+      # nothing has ever needed. `Modulo`/`Size`/`First`/`Last` stay in
       # (each is its own trailing `.method(...)`/`.method` call, so
       # `Resolver.parse`'s greedy `(.+)\.suffix\z` regexes correctly
       # isolate them as a receiver regardless of what precedes them —
@@ -323,8 +323,8 @@ module Hecks
       def resolver_numeric_leaves(depth)
         return leaves(:numeric) if depth <= 0
 
-        # SELF-referential on purpose, one depth down — `Modulo`'s own
-        # receiver needs the SAME restriction `resolver_numeric_leaves`
+        # Self-referential on purpose, one depth down — `Modulo`'s own
+        # receiver needs the same restriction `resolver_numeric_leaves`
         # exists to express in the first place (see its own header
         # comment); the argument stays the full, unrestricted set, same
         # as `numeric_productions`' identical split right above.
@@ -336,8 +336,8 @@ module Hecks
       end
 
       # STRING ← ToS(numeric | boolean | nil | string) | First/Last(string
-      # array). `Split` produces an ARRAY, never a String (resolver.rb's
-      # own `apply_split`) — deliberately NOT listed as a string producer
+      # array). `Split` produces an array, never a String (resolver.rb's
+      # own `apply_split`) — deliberately not listed as a string producer
       # here; that would be exactly the "vocabulary-legal but grammar-
       # can't-actually-produce-it" mistake this sublanguage's own
       # `ArrayLiteral` bug (§1 of this generator's own design report) was
@@ -353,8 +353,8 @@ module Hecks
       # ARRAY ← Split(string, separator) | ArrayLiteral[same-type
       # elements] | the synthetic array attributes (already in `leaves`).
       # Kept deliberately small relative to numeric/string/boolean —
-      # `array` is overwhelmingly a RECEIVER type in this grammar (`.size`
-      # /`.any?`/`.include?`/…), rarely a produced VALUE; the two real
+      # `array` is overwhelmingly a receiver type in this grammar (`.size`
+      # /`.any?`/`.include?`/…), rarely a produced value; the two real
       # producers are enough to exercise every array-typed consumer
       # elsewhere in this file at least once via a non-leaf path.
       def array_productions(depth)
@@ -367,11 +367,11 @@ module Hecks
       def numeric_array_literal(depth) = "[#{bounded(:numeric, depth).first(2).join(', ')}]"
       def string_array_literal(depth)  = "[#{bounded(:string, depth).first(2).join(', ')}]"
 
-      # Arrays KNOWN (by construction, not merely by type) to hold numeric
+      # Arrays known (by construction, not merely by type) to hold numeric
       # elements — the two synthetic array attributes (`ARRAY_ELEMENT_TYPE`
-      # tags `arr_num`) plus any numeric-array LITERAL this same depth
+      # tags `arr_num`) plus any numeric-array literal this same depth
       # budget can build. `.first`/`.last`/block predicates need to know
-      # the ELEMENT type, which plain `array_productions` doesn't carry —
+      # the element type, which plain `array_productions` doesn't carry —
       # this (and `string_array_productions`, its twin) is how that extra
       # bit of type information flows without inventing a second, richer
       # AST just to carry it.
@@ -387,8 +387,8 @@ module Hecks
       end
 
       # BOOLEAN ← every comparison/predicate construct in the grammar.
-      # This is where almost all of the sublanguage's OWN real surface
-      # lives — a `given`/`invariant`/`ensures` body is ALWAYS boolean-
+      # This is where almost all of the sublanguage's own real surface
+      # lives — a `given`/`invariant`/`ensures` body is always boolean-
       # typed at its own top level (`Evaluator.truthy?`), so this is also
       # the set `all_predicates` (below) draws its top-level cases from
       # directly.
@@ -433,14 +433,14 @@ module Hecks
           include_productions(depth - 1)
       end
 
-      # `.all?`/`.any?`/`.none?` over EACH known-element-typed array
+      # `.all?`/`.any?`/`.none?` over each known-element-typed array
       # source, with a predicate body drawn from `boolean_productions` at
-      # ONE LESS depth, evaluated against `BLOCK_PARAM` bound to the
-      # array's own element type — this is the ONLY place `Resolver` and
+      # one less depth, evaluated against `BLOCK_PARAM` bound to the
+      # array's own element type — this is the only place `Resolver` and
       # `Evaluator` are truly mutually recursive (a `BlockPredicate`'s own
       # `predicate` field is a full `Evaluator` AST, not a `Resolver`
       # leaf — confirmed directly), and the only construct in this whole
-      # generator that can nest into ANOTHER block predicate (the real
+      # generator that can nest into another block predicate (the real
       # corpus already does this two levels deep —
       # `examples/roster/bluebook/roster.bluebook`'s own `seats.any? { |s|
       # assignments.none? { |a| … } }`).
@@ -458,14 +458,14 @@ module Hecks
       end
 
       # The predicate body a block gets — `boolean_productions`, but with
-      # `BLOCK_PARAM` (bound to `element_type`) ALSO admitted as a leaf,
+      # `BLOCK_PARAM` (bound to `element_type`) also admitted as a leaf,
       # since inside the block it is exactly as usable as any other
       # `Lookup` name (resolver.rb's own `interpret_with_element`: the
       # bound element joins `attrs` for the span of one evaluation, no
       # different from a top-level attribute — confirmed directly).
       # `sample`d for the same reason every other internal list is — this
-      # feeds THREE more constructs per body (`all?`/`any?`/`none?`) times
-      # FOUR array sources, so an unbounded body list here is exactly the
+      # feeds three more constructs per body (`all?`/`any?`/`none?`) times
+      # four array sources, so an unbounded body list here is exactly the
       # kind of multiplier this file's own `bounded` comment warns about.
       def predicate_bodies(element_type, depth)
         sample(with_element_leaf(element_type) { boolean_productions(depth) })
@@ -473,7 +473,7 @@ module Hecks
 
       # `haystack.include?(needle)` — String haystack needs a String
       # needle (raises otherwise, evaluator.rb's own `includes?`); Array
-      # haystack admits ANY needle type (compared via `equal?`, itself
+      # haystack admits any needle type (compared via `equal?`, itself
       # numeric-coerced-first). Both sides generated here, matching
       # `Vocabulary::IncludeHaystack` exactly.
       def include_productions(depth)
@@ -487,23 +487,23 @@ module Hecks
           end
       end
 
-      # SAMPLED, NOT A FULL CROSS PRODUCT — a full `list.product(list)`
+      # **Sampled, not a full cross product** — a full `list.product(list)`
       # is what actually explodes this generator (numeric productions
-      # alone hit 8000+ by depth 2; squaring THAT for `&&`/`==` pairs is
+      # alone hit 8000+ by depth 2; squaring that for `&&`/`==` pairs is
       # where "tens of thousands" becomes tens of millions). The
       # combinatorics genuinely don't buy proof coverage: proving `Or`/
-      # `And`/`Not` themselves never crash needs ONE representative pair
+      # `And`/`Not` themselves never crash needs one representative pair
       # per depth (`evaluator.rb`'s own `interpret` does zero type-
       # dependent work for those three — `interpret(left) || interpret
       # (right)`, plain Ruby, no coercion, no receiver-type check at
-      # all — so a crash there could only come from LEFT or RIGHT
+      # all — so a crash there could only come from left or right
       # themselves, already covered by testing every operand on its own
       # elsewhere in this same predicate set). `Compare`/`Include`/
-      # `Addition`/`Modulo` genuinely DO real per-pair type coercion
+      # `Addition`/`Modulo` genuinely do real per-pair type coercion
       # (`Evaluator.apply`/`less_than`/`Resolver.add`/`apply_modulo`), so
-      # THOSE stay covered across every construct SHAPE at every depth —
+      # those stay covered across every construct shape at every depth —
       # just sampled evenly across each side's own operand set (leaves
-      # AND deep productions alike, not just whichever the list happens
+      # and deep productions alike, not just whichever the list happens
       # to enumerate first) rather than every possible pairing of them.
       SAMPLE_CAP = 14
 
@@ -514,13 +514,13 @@ module Hecks
         sampled.product(sampled)
       end
 
-      # `pairs`' own two-different-lists twin — used wherever the LEFT
-      # and RIGHT of a construct have genuinely different safety
+      # `pairs`' own two-different-lists twin — used wherever the left
+      # and right of a construct have genuinely different safety
       # requirements (`Modulo`'s own receiver vs. argument, below) and
-      # squaring the SAME sampled list wouldn't be correct.
+      # squaring the same sampled list wouldn't be correct.
       def cross(left, right) = sample(left).product(sample(right))
 
-      # THE FULL SET — every boolean-typed expression up to `MAX_DEPTH`,
+      # The full set — every boolean-typed expression up to `MAX_DEPTH`,
       # deduplicated (many shorter expressions are also produced, re-
       # wrapped, at every deeper level — `.uniq` inside `productions`
       # already collapses most of that; this is the final pass over the
@@ -531,8 +531,8 @@ module Hecks
 
       # Interprets one predicate against the shared synthetic
       # state/attrs, returning `{ok: true, result: ...}` on any outcome
-      # `Evaluator.call` itself can express (a real true/false answer, OR
-      # a clean `EvaluationError` — both are the sublanguage WORKING
+      # `Evaluator.call` itself can express (a real true/false answer, or
+      # a clean `EvaluationError` — both are the sublanguage working
       # correctly, never a finding) and `{ok: false, error: ...}` only
       # for anything else escaping — the one shape this whole file exists
       # to prove never happens for well-typed input.

data/lib/hecks/fuzzing/combination_miner.rb

@@ -0,0 +1,119 @@
+require "json"
+require "open3"
+require_relative "form_census"
+
+module Hecks
+  module Fuzzing
+    # An agent reads the adversarial corpus and writes the next meeting.
+    #
+    # `DomainGenerator` forces two `FormCensus::FORMS` onto one aggregate
+    # from a seed — cheap, mechanical, and blind to why a combination
+    # should break. The bugs the ledger actually logged came from someone
+    # reading a stress domain, a bug title, and a runtime file side by
+    # side and guessing where the next divergence lives (`corrections`
+    # from BUG#30-33, `case_escalation` from ADR 0037 Finding 5 meeting
+    # `corrects`). This is that guess, delegated: the mechanical half
+    # (what the corpus already puts together, which pairs nothing meets,
+    # what the recent bugs were) is computed here; the judgment half is a
+    # prompt (`qa/combination_miner/prompt.md`) an agent answers by
+    # writing candidate bluebooks, each with a hypothesis. Checking them
+    # is not this module's job — `bin/qa_mine_combinations` hands every
+    # valid candidate to `bin/qa_generated_domains --source`, the same
+    # differential, self-consistency, Rust build and shrinking path a
+    # generated domain takes.
+    #
+    # **Opt-in, never the rotation**. An agent call costs money and minutes
+    # and answers differently every time; `bin/qa_tick` never runs it and
+    # no `QualityControlDials` entry turns it on. A person runs
+    # `bin/qa_mine_combinations` when they want new shapes.
+    module CombinationMiner
+      PROMPT_TEMPLATE = "qa/combination_miner/prompt.md".freeze
+      HYPOTHESIS_FILE = "HYPOTHESIS.md".freeze
+
+      module_function
+
+      # Every adversarial domain plus every example — the corpus the
+      # census is measured over. Promoted generated domains are included:
+      # their shapes are already swept too.
+      def corpus_paths(root)
+        Hecks::Corpus.members(:stress, :example, root: root).map(&:path)
+                     .select { |path| Hecks::Corpus.bluebook_files(path) }
+                     .sort
+      end
+
+      # The last `limit` bug commit subjects on this branch — cheap, needs
+      # no ledger or Postgres, and names the mechanism in the title by
+      # convention (`BUG#n: …`).
+      def recent_bug_titles(root, limit: 60)
+        out, status = Open3.capture2("git", "log", "--format=%s", "--grep=BUG#", "-n", limit.to_s, chdir: root)
+        status.success? ? out.lines.map(&:strip).reject(&:empty?) : []
+      end
+
+      # The mechanical half: which form pairs the corpus meets (and by
+      # whom), which it never meets, and what could not be measured.
+      def brief(paths, root:, bug_titles:)
+        covered = Hash.new { |hash, key| hash[key] = [] }
+        skipped = []
+        paths.each do |path|
+          FormCensus.covered_pairs(FormCensus.census(path)).each { |pair, names| covered[pair].concat(names) }
+        rescue StandardError, ScriptError => e
+          skipped << "#{relative(path, root)} (#{e.class}: #{e.message.lines.first&.strip})"
+        end
+        { "forms" => FormCensus::FORMS.keys, "corpus" => paths.map { |path| relative(path, root) },
+          "unmet_pairs" => (FormCensus.pairs - covered.keys).sort,
+          "single_carrier_pairs" => covered.select { |_, names| names.uniq.size == 1 }
+                                           .map { |pair, names| "#{pair} (only #{names.first})" }.sort,
+          "skipped" => skipped, "recent_bugs" => bug_titles, "covered" => covered }
+      end
+
+      def prompt(root, brief, count:, out_dir:)
+        substitutions = {
+          "count" => count.to_s, "out_dir" => out_dir, "forms" => brief["forms"].join(", "),
+          "corpus" => bulleted(brief["corpus"]), "unmet_pairs" => bulleted(brief["unmet_pairs"]),
+          "single_carrier_pairs" => bulleted(brief["single_carrier_pairs"]),
+          "recent_bugs" => bulleted(brief["recent_bugs"]), "skipped" => bulleted(brief["skipped"])
+        }
+        File.read(File.join(root, PROMPT_TEMPLATE)).gsub(/\{\{(\w+)\}\}/) { substitutions.fetch(Regexp.last_match(1)) }
+      end
+
+      # The second, narrower ask: these candidates did not boot, here is
+      # why, fix them in place. Nothing else in the directory changes.
+      def repair_prompt(failures, out_dir:)
+        listed = failures.map { |candidate, error| "- #{candidate[:bluebook]}\n  boot error: #{error}" }.join("\n")
+        <<~PROMPT
+          REPAIR ROUND. You wrote candidate Hecks bluebooks under #{out_dir} for the QA combination miner.
+          These did not boot. Edit each file IN PLACE so it boots, keeping the construct combination its
+          #{HYPOTHESIS_FILE} names (update the hypothesis if the fix changes the shape). Do not create new
+          candidates and do not touch anything outside #{out_dir}.
+
+          #{listed}
+        PROMPT
+      end
+
+      # `<out_dir>/<slug>/<anything>.bluebook` plus an optional
+      # HYPOTHESIS.md beside it. One bluebook per candidate: the first,
+      # alphabetically, if an agent wrote more.
+      def candidates(out_dir)
+        Dir[File.join(out_dir, "*")].select { |dir| File.directory?(dir) }.sort.filter_map do |dir|
+          bluebook = Dir[File.join(dir, "*.bluebook")].min
+          next unless bluebook
+
+          hypothesis = File.join(dir, HYPOTHESIS_FILE)
+          { slug: File.basename(dir), dir: dir, bluebook: bluebook,
+            hypothesis: File.exist?(hypothesis) ? File.read(hypothesis).strip : nil }
+        end
+      end
+
+      # Pairs the candidate meets on one aggregate that no corpus domain
+      # does — informational, never a gate: an agent may be aiming at a
+      # shape the census does not name yet.
+      def new_pairs(candidate_dir, covered)
+        FormCensus.covered_pairs(FormCensus.census(candidate_dir)).keys.reject { |pair| covered.key?(pair) }.sort
+      end
+
+      def relative(path, root) = path.delete_prefix("#{root}/")
+
+      def bulleted(items) = items.empty? ? "(none)" : items.map { |item| "- #{item}" }.join("\n")
+    end
+  end
+end