hecks 1.4.0 → 1.5.0

data/lib/hecks/framework.rb

@@ -6,6 +6,8 @@ module Hecks
   # domain-agnostic chapters no single example owns, shared by reference
   # rather than copied into every domain that wants one.
   #
+  # ## Where it lives
+  #
   # Under `lib/`, not a top-level sibling — a real consumer (embryonaut)
   # vendors only `lib/` (`bin/vendor-hecks`, and this gem's own
   # `hecks.gemspec`, both glob `lib/**/*`), so a `framework/`
@@ -19,6 +21,8 @@ module Hecks
   # non-Ruby data a module owns lives inside `lib/` with the code that
   # reads it, not beside it.
   #
+  # ## Derived, not hand-listed
+  #
   # Derived from the directory, not hand-listed a second time — the same
   # reasoning `Assembly::CONTRACTS` gives for reading the language's own
   # fields from a table instead of restating them: a member added here
@@ -27,19 +31,13 @@ module Hecks
   # stale in silence. `spec/corpus_spec.rb`'s own `FRAMEWORK_MEMBERS`
   # glob is the precedent this mirrors.
   #
+  # ## Naming
+  #
   # Named by file stem, capitalized — `governance.bluebook` holds
   # `Hecks.bluebook "Governance"`, the same one-to-one spelling every
   # other chapter in this codebase already keeps between its filename
   # and its declared name.
   module Framework
-    ROOT = File.expand_path("framework/bluebook", __dir__).freeze
-
-    def self.members
-      Dir.glob(File.join(ROOT, "*.bluebook")).to_h do |path|
-        [Naming.pascal(File.basename(path, ".bluebook")), path]
-      end
-    end
-
     # Loaded from its own real path, always — never a copy. A domain
     # booted through `Fuzzing::IsolatedBoot`'s tmp-directory copy still
     # reaches the same `framework/bluebook/governance.bluebook` this
@@ -64,28 +62,36 @@ module Hecks
     # everywhere else too. See `examples/banking/bluebook/banking.hecksagon`
     # for the pattern — a real `.hecksagon` file can hold more than one
     # `Hecks.hecksagon` call, one per domain it wires.
-    # Idempotent, per registry — `uses_framework` is now called more than
-    # once for the same member within a single boot (S8: a domain
-    # attaching Governance for its own role check, plus a framework
-    # sibling attaching it too, e.g. `banking.hecksagon`'s Identity
-    # block). `Kernel.load` always re-executes the file, unlike
-    # `require`, so a second call would re-run `Hecks.bluebook
-    # "Governance"` a second time — and the self-hosting meta-domain
-    # records every declaration as a real dispatched command against its
-    # own ledger, so a second `Declare` for the same aggregate is a real
-    # `AlreadyExists`, not a no-op. Skipped once the member's bluebook is
-    # already registered in this registry — the same chapter, not merely
-    # a same-named one from a stale prior boot.
+    ROOT = File.expand_path("framework/bluebook", __dir__).freeze
+
+    # Every framework member available to attach, by declared name.
+    #
+    # @return [Hash{String => String}] each member's capitalized bluebook name,
+    #   mapped to the absolute path of its `.bluebook` file
+    def self.members
+      Dir.glob(File.join(ROOT, "*.bluebook")).to_h do |path|
+        [Naming.pascal(File.basename(path, ".bluebook")), path]
+      end
+    end
+
     # Every member whose own bluebook declares `provides capability` —
     # read off the member's real IR (each loaded into a scratch registry,
     # never the caller's), not off its name. Used where a check needs to
     # say which member would satisfy it (`refuse_ungoverned_roles!`'s own
     # suggestion, `Fuzzing::TargetCapabilities`).
+    #
+    # @param capability [String, Symbol] the capability name to look for
+    # @return [Array<String>] the names of every framework member that provides it,
+    #   sorted
     def self.providers_of(capability)
       members.keys.select { |name| chapter(name).provides?(capability) }.sort
     end
 
     # One member's chapter, built in isolation.
+    #
+    # @param name [String, Symbol] the member's name, such as `"Governance"`
+    # @return [Bluebook::Chapter] the member's chapter, loaded into a scratch registry
+    # @raise [Runtime::WiringError] if no framework member has that name
     def self.chapter(name)
       path = members.fetch(name.to_s) do
         raise Runtime::WiringError,
@@ -107,6 +113,23 @@ module Hecks
       registry.bluebook(name.to_s)
     end
 
+    # Idempotent, per registry — `uses_framework` is now called more than
+    # once for the same member within a single boot (S8: a domain
+    # attaching Governance for its own role check, plus a framework
+    # sibling attaching it too, e.g. `banking.hecksagon`'s Identity
+    # block). `Kernel.load` always re-executes the file, unlike
+    # `require`, so a second call would re-run `Hecks.bluebook
+    # "Governance"` a second time — and the self-hosting meta-domain
+    # records every declaration as a real dispatched command against its
+    # own ledger, so a second `Declare` for the same aggregate is a real
+    # `AlreadyExists`, not a no-op. Skipped once the member's bluebook is
+    # already registered in this registry — the same chapter, not merely
+    # a same-named one from a stale prior boot.
+    #
+    # @param name [String, Symbol] the member's name, such as `"Governance"`
+    # @return [Boolean, nil] true when this call loaded the member's bluebook, nil when
+    #   the current registry already held it
+    # @raise [Runtime::WiringError] if no framework member has that name
     def self.load!(name)
       path = members.fetch(name.to_s) do
         raise Runtime::WiringError,

data/lib/hecks/freezer.rb

@@ -8,7 +8,7 @@ module Hecks
   # Hash a field holds stays mutable, so a caller reaches straight
   # through and edits in place. Each fix looked complete and none was.
   #
-  # What should be frozen, and why it is not everything:
+  # ## What should be frozen, and why it is not everything
   #
   #   a value object has no identity to change over. `with` already
   #   answers a new one rather than mutating, so freezing it through is
@@ -33,6 +33,10 @@ module Hecks
     # Numbers, symbols, nil and booleans are already immediate or frozen;
     # a Value froze itself when it was built. What is left is the mutable
     # trio, and each has to be walked rather than topped.
+    #
+    # @param held [Object] any domain value
+    # @return [Object] `held`, recursively frozen if it is a Hash, Array, or
+    #   String; returned unchanged otherwise
     def deep(held)
       case held
       when Hash   then held.each_value { |inner| deep(inner) }.freeze
@@ -45,11 +49,20 @@ module Hecks
     # The question a gate asks, rather than the act. Answers false for the
     # first thing that is reachable and mutable, which is what makes a
     # failure message worth reading.
+    #
+    # @param held [Object] any domain value
+    # @return [Boolean] true if `held` and everything reachable from it is frozen
     def deeply_frozen?(held) = unfrozen_within(held).nil?
 
     # The path to the first mutable thing reachable from `held`, or nil.
     # A path rather than a boolean because "something in this event is
     # mutable" is not an actionable sentence.
+    #
+    # @param held [Object] any domain value
+    # @param path [Array<String>] the owner path accumulated by the recursive
+    #   walk so far; callers pass nothing and get the default
+    # @return [String, nil] the dotted path (Hash keys, Array indices, or
+    #   `"(the value itself)"`) to the first mutable value found, or nil if none
     def unfrozen_within(held, path = [])
       return (path.empty? ? "(the value itself)" : path.join(".")) unless immune?(held) || held.frozen?
 
@@ -62,6 +75,9 @@ module Hecks
     # Immediates are frozen in every Ruby that matters, but asking
     # `frozen?` of them and trusting the answer has bitten enough people
     # that it is worth being explicit.
+    #
+    # @param held [Object] any domain value
+    # @return [Boolean] true if `held` is nil, true, false, a Numeric, or a Symbol
     def immune?(held) = held.nil? || held == true || held == false || held.is_a?(Numeric) || held.is_a?(Symbol)
   end
 end

data/lib/hecks/fuzzing/bounded_exhaustive_expressions.rb

@@ -20,6 +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 generation
+    #
     # 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,
@@ -36,7 +38,9 @@ module Hecks
     # 3" claim for exactly the sublanguage that already bit this project
     # twice.
     #
-    # **What "PROVEN" means here, precisely**: every expression this generator
+    # ## 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
@@ -133,20 +137,25 @@ module Hecks
       # 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-
-      # 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
-      # `Addition`/`Compare`/every scalar-typed operation with "expects a
-      # 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.
+      # field record has no single scalar to collapse to). A plain
+      # `{value: X}` Hash cannot stand in here: `is_a?(Hash)` is true for
+      # it, so `unwrap_scalar` leaves it wrapped, and every VO-typed
+      # synthetic attribute then fails `Addition`/`Compare`/every
+      # scalar-typed operation with "expects a number, got
+      # {\"value\":5}" — a bug in this generator's own synthetic state,
+      # not in `Resolver`, that would surface only as `num_b == 5`
+      # (`num_b` a plain `{value: 5}` Hash) evaluating to `false` instead
+      # of `true`.
       SingleFieldVO = Struct.new(:value) do
         def to_h = { value: value }
       end
 
+      # Builds the fixed state every generated predicate is interpreted against.
+      #
+      # @return [Hash{Symbol => Object}] symbol-keyed synthetic state: half bare
+      #   scalars (`num_a`, `str_a`, `bool_a`, half of `arr_num`'s/`arr_str`'s
+      #   elements), half wrapped `SingleFieldVO` instances (`num_b`, `str_b`,
+      #   `bool_b`, the other half)
       def synthetic_state
         {
           num_a:   3,
@@ -160,18 +169,27 @@ module Hecks
         }
       end
 
+      # The `attrs` half of the interpret call — always empty, since every
+      # synthetic name this generator uses lives in `synthetic_state` instead.
+      #
+      # @return [Hash] always `{}`
       def synthetic_attrs = {}
 
-      # `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
-      # would write; `synthetic_state`, above, is what gives those names
-      # meaning at `interpret` time).
+      # Lists 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 would write; `synthetic_state`,
+      # above, is what gives those names meaning at `interpret` time).
+      #
+      # @param type [Symbol] one of `TYPES`
+      # @return [Array<String>] `type`'s literal palette, synthetic attribute
+      #   names, and any currently-bound block-parameter leaf for `type`
       def leaves(type)
         (TYPE_LEAVES[type] || []) + (SYNTHETIC_ATTRS[type] || []) + Array(bound_leaves[type])
       end
 
+      # The per-type stack of currently-bound block-parameter leaf names.
+      #
       # 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
@@ -184,8 +202,20 @@ module Hecks
       # outer level already bound, so a shadowed name still interprets
       # correctly — this generator is proving "does it crash," not "is
       # every generated predicate semantically distinct."
+      #
+      # @return [Hash{Symbol => Array<String>}] each type's own stack of bound
+      #   leaf names, usually `[]` or `["el"]`
       def bound_leaves = @bound_leaves ||= Hash.new { |h, k| h[k] = [] }
 
+      # Runs the block with `BLOCK_PARAM` admitted as a leaf of `element_type`,
+      # for building a block predicate's own body.
+      #
+      # @param element_type [Symbol] the type `BLOCK_PARAM` is bound to for the
+      #   duration of the block
+      # @yield runs with the leaf pushed and any cached `element_type` productions
+      #   invalidated
+      # @yieldreturn [Object] the block's own result
+      # @return [Object] the block's own result, unchanged
       def with_element_leaf(element_type)
         bound_leaves[element_type] << BLOCK_PARAM
         cache.delete_if { |(type, _depth), _| type == element_type }
@@ -195,13 +225,18 @@ module Hecks
         cache.delete_if { |(type, _depth), _| type == element_type }
       end
 
-      # `productions(type, depth)` — every expression of `type` reachable
-      # 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)
-      # says can produce `type`, built from `depth - 1` sub-expressions.
+      # Lists every expression of `type` reachable 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 production methods (below) say can produce `type`, built
+      # from `depth - 1` sub-expressions.
+      #
+      # @param type [Symbol] one of `TYPES`
+      # @param depth [Integer] maximum recursive steps remaining
+      # @return [Array<String>] every expression of `type` reachable in at most
+      #   `depth` steps, deduplicated
       def productions(type, depth)
         cache[[type, depth]] ||= begin
           base = leaves(type)
@@ -209,8 +244,18 @@ module Hecks
         end
       end
 
+      # The `productions` memo, keyed by `[type, depth]`.
+      #
+      # @return [Hash{Array(Symbol, Integer) => Array<String>}] the memoized productions cache
       def cache = @cache ||= {}
 
+      # Dispatches to the recursive (non-leaf) production rule for `type`.
+      #
+      # @param type [Symbol] one of `TYPES`
+      # @param depth [Integer] maximum recursive steps remaining
+      # @return [Array<String>] every non-leaf expression of `type` reachable in at
+      #   most `depth` steps; `[]` for `:nil_type`, which has no recursive producer
+      # @raise [ArgumentError] if `type` names anything outside `TYPES`
       def recursive_productions(type, depth)
         case type
         when :numeric  then numeric_productions(depth)
@@ -237,12 +282,21 @@ module Hecks
       # final output) keeps the shape diversity `sample`'s even-spacing
       # already preserves while keeping growth roughly linear in depth
       # instead of combinatorial.
+      #
+      # @param type [Symbol] one of `TYPES`
+      # @param depth [Integer] maximum recursive steps remaining
+      # @return [Array<String>] `productions(type, depth)`, sampled down to at most
+      #   `SAMPLE_CAP` entries
       def bounded(type, depth) = sample(productions(type, depth))
 
       # 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` —
       # `size_of`, resolver.rb) — both sides generated here.
+      #
+      # @param depth [Integer] maximum recursive steps remaining
+      # @return [Array<String>] numeric expressions one construct deep: `Addition`,
+      #   `Modulo`, `Size` (of a string or array), `First`/`Last` (of a numeric array)
       def numeric_productions(depth)
         sub = bounded(:numeric, depth - 1)
         # `Modulo`'s own receiver (not its argument — that side already
@@ -290,6 +344,11 @@ module Hecks
       # `StartsWith`/`EndsWith`, `BlockPredicate` — every one of them
       # parsed via a suffix regex inside `Resolver.parse` itself, per
       # this generator's own design report) are eligible here.
+      #
+      # @param depth [Integer] maximum recursive steps remaining
+      # @return [Array<String>] boolean-typed expressions safe to embed as a
+      #   Resolver-level suffix receiver: literals/lookups, sign tests, string
+      #   predicates, `.empty?`, and sampled block predicates
       def resolver_boolean_leaves(depth)
         leaves(:boolean) +
           resolver_numeric_leaves(depth).flat_map { |n| ["#{n}.positive?", "#{n}.negative?", "#{n}.zero?"] } +
@@ -320,6 +379,10 @@ module Hecks
       # `Resolver.parse`'s greedy `(.+)\.suffix\z` regexes correctly
       # isolate them as a receiver regardless of what precedes them —
       # only bare top-level `+` has this problem).
+      #
+      # @param depth [Integer] maximum recursive steps remaining
+      # @return [Array<String>] numeric-typed expressions safe to embed as a
+      #   Resolver-level suffix receiver (never a bare top-level `Addition`)
       def resolver_numeric_leaves(depth)
         return leaves(:numeric) if depth <= 0
 
@@ -342,6 +405,10 @@ module Hecks
       # can't-actually-produce-it" mistake this sublanguage's own
       # `ArrayLiteral` bug (§1 of this generator's own design report) was
       # found from, inverted.
+      #
+      # @param depth [Integer] maximum recursive steps remaining
+      # @return [Array<String>] string expressions one construct deep: `ToS` of a
+      #   numeric, boolean, nil, or string operand, or `First`/`Last` of a string array
       def string_productions(depth)
         sample(resolver_numeric_leaves(depth - 1)).map { |n| "#{n}.to_s" } +
           sample(resolver_boolean_leaves(depth - 1)).map { |b| "#{b}.to_s" } +
@@ -357,6 +424,10 @@ module Hecks
       # /`.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.
+      #
+      # @param depth [Integer] maximum recursive steps remaining
+      # @return [Array<String>] array expressions one construct deep: a string
+      #   `Split`, a numeric array literal, and a string array literal; `[]` at depth 0
       def array_productions(depth)
         return [] if depth <= 0
 
@@ -364,7 +435,16 @@ module Hecks
           [numeric_array_literal(depth - 1), string_array_literal(depth - 1)]
       end
 
+      # Builds a two-element numeric array literal at `depth`.
+      #
+      # @param depth [Integer] maximum recursive steps remaining for its own elements
+      # @return [String] a `"[a, b]"` numeric array literal source text
       def numeric_array_literal(depth) = "[#{bounded(:numeric, depth).first(2).join(', ')}]"
+
+      # Builds a two-element string array literal at `depth`.
+      #
+      # @param depth [Integer] maximum recursive steps remaining for its own elements
+      # @return [String] a `"[a, b]"` string array literal source text
       def string_array_literal(depth)  = "[#{bounded(:string, depth).first(2).join(', ')}]"
 
       # Arrays known (by construction, not merely by type) to hold numeric
@@ -375,6 +455,10 @@ module Hecks
       # 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.
+      #
+      # @param depth [Integer] maximum recursive steps remaining
+      # @return [Array<String>] array expressions known to hold numeric elements:
+      #   `"arr_num"`, plus a numeric array literal at `depth`
       def numeric_array_productions(depth)
         ["arr_num", numeric_array_literal(depth)]
         # a Split of a string never yields numeric elements — no third
@@ -382,6 +466,12 @@ module Hecks
         # `string_array_productions`, its non-empty twin, right below).
       end
 
+      # Arrays known (by construction) to hold string elements — `arr_str`'s
+      # own twin of `numeric_array_productions`, above.
+      #
+      # @param depth [Integer] maximum recursive steps remaining
+      # @return [Array<String>] `"arr_str"`, a string array literal at `depth`, and
+      #   every string `Split` expression at `depth`
       def string_array_productions(depth)
         ["arr_str", string_array_literal(depth)] + bounded(:string, depth).map { |s| "#{s}.split(\",\")" }
       end
@@ -401,6 +491,12 @@ module Hecks
       # need `sub`/`num`/`str` threaded into each as parameters and
       # would separate every rule from the comment justifying it.
       # rubocop:disable-next Metrics/AbcSize
+      #
+      # @param depth [Integer] maximum recursive steps remaining
+      # @return [Array<String>] every boolean-typed construct in the grammar, one
+      #   level deep: comparisons, sign tests, `.empty?`/`.match?`/`.present?`/
+      #   `.blank?`/`.start_with?`/`.end_with?`, `&&`/`||`/`!`, block predicates,
+      #   and `include?`
       def boolean_productions(depth)
         sub = bounded(:boolean, depth - 1)
         num = bounded(:numeric, depth - 1)
@@ -444,6 +540,11 @@ module Hecks
       # corpus already does this two levels deep —
       # `examples/roster/bluebook/roster.bluebook`'s own `seats.any? { |s|
       # assignments.none? { |a| … } }`).
+      #
+      # @param depth [Integer] maximum recursive steps remaining for the predicate body
+      # @return [Array<String>] `.all?`/`.any?`/`.none?` calls over each
+      #   known-element-typed array source, one per predicate body `predicate_bodies`
+      #   produces; `[]` if `depth` is negative
       def block_predicate_productions(depth)
         return [] if depth.negative?
 
@@ -467,6 +568,11 @@ module Hecks
       # 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.
+      #
+      # @param element_type [Symbol] the type `BLOCK_PARAM` is bound to inside the block
+      # @param depth [Integer] maximum recursive steps remaining for the body
+      # @return [Array<String>] a sampled set of boolean expressions, with
+      #   `BLOCK_PARAM` admitted as a leaf of `element_type`
       def predicate_bodies(element_type, depth)
         sample(with_element_leaf(element_type) { boolean_productions(depth) })
       end
@@ -476,6 +582,11 @@ module Hecks
       # haystack admits any needle type (compared via `equal?`, itself
       # numeric-coerced-first). Both sides generated here, matching
       # `Vocabulary::IncludeHaystack` exactly.
+      #
+      # @param depth [Integer] maximum recursive steps remaining
+      # @return [Array<String>] `haystack.include?(needle)` expressions: a String
+      #   haystack with a String needle, or a numeric/string array haystack with a
+      #   matching-type needle
       def include_productions(depth)
         str = bounded(:string, depth)
         pairs(str).map { |haystack, needle| "#{haystack}.include?(#{needle})" } +
@@ -507,8 +618,18 @@ module Hecks
       # to enumerate first) rather than every possible pairing of them.
       SAMPLE_CAP = 14
 
+      # Evenly samples `list` down to at most `SAMPLE_CAP` entries, so a list
+      # size never compounds unbounded across recursive passes.
+      #
+      # @param list [Array<String>] the list to sample
+      # @return [Array<String>] `list` unchanged if it is at most `SAMPLE_CAP` entries;
+      #   otherwise every `list.size.fdiv(SAMPLE_CAP).ceil`-th entry, evenly spaced
       def sample(list) = list.size <= SAMPLE_CAP ? list : list.each_slice(list.size.fdiv(SAMPLE_CAP).ceil).map(&:first)
 
+      # Builds every pair of one sampled list with itself.
+      #
+      # @param list [Array<String>] the list to sample and pair with itself
+      # @return [Array<Array(String, String)>] the sampled list's own self cross product
       def pairs(list)
         sampled = sample(list)
         sampled.product(sampled)
@@ -518,6 +639,10 @@ module Hecks
       # 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.
+      #
+      # @param left [Array<String>] the left-hand list to sample
+      # @param right [Array<String>] the right-hand list to sample
+      # @return [Array<Array(String, String)>] the two sampled lists' own cross product
       def cross(left, right) = sample(left).product(sample(right))
 
       # The full set — every boolean-typed expression up to `MAX_DEPTH`,
@@ -525,6 +650,10 @@ module Hecks
       # wrapped, at every deeper level — `.uniq` inside `productions`
       # already collapses most of that; this is the final pass over the
       # complete depth-`MAX_DEPTH` set specifically).
+      #
+      # @param max_depth [Integer] maximum recursive depth to generate up to
+      # @return [Array<String>] every boolean-typed expression up to `max_depth`,
+      #   deduplicated
       def all_predicates(max_depth = MAX_DEPTH)
         productions(:boolean, max_depth).uniq
       end
@@ -536,6 +665,12 @@ module Hecks
       # 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.
+      #
+      # @param expr [String] a generated (or hand-written) expression source string
+      # @return [Hash{Symbol => Object}] `{ok: true, result: Object}` for a real
+      #   answer, `{ok: true, result: :refused, message: String}` for a clean
+      #   `EvaluationError`, or `{ok: false, error: StandardError}` for anything else
+      #   escaping
       def check(expr)
         result = Hecks::Bluebook::Expression::Evaluator.call(expr, synthetic_state, synthetic_attrs)
         { ok: true, result: result }

data/lib/hecks/fuzzing/combination_miner.rb

@@ -35,6 +35,10 @@ module Hecks
       # Every adversarial domain plus every example — the corpus the
       # census is measured over. Promoted generated domains are included:
       # their shapes are already swept too.
+      #
+      # @param root [String] repository root to search under
+      # @return [Array<String>] paths of every stress/example corpus member that
+      #   declares at least one bluebook file
       def corpus_paths(root)
         Hecks::Corpus.members(:stress, :example, root: root).map(&:path)
                      .select { |path| Hecks::Corpus.bluebook_files(path) }
@@ -44,6 +48,11 @@ module Hecks
       # 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: …`).
+      #
+      # @param root [String] repository root to run `git log` in
+      # @param limit [Integer] maximum number of commit subjects to return
+      # @return [Array<String>] matching commit subjects, newest first; empty if
+      #   `git log` fails
       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?) : []
@@ -51,6 +60,20 @@ module Hecks
 
       # The mechanical half: which form pairs the corpus meets (and by
       # whom), which it never meets, and what could not be measured.
+      #
+      # @param paths [Array<String>] corpus member paths to census, as returned by
+      #   `#corpus_paths`
+      # @param root [String] repository root, to render `paths` relative to it
+      # @param bug_titles [Array<String>] recent bug commit subjects, as returned
+      #   by `#recent_bug_titles`
+      # @return [Hash] `"forms"` (`Array<String>`, every declared form name),
+      #   `"corpus"` (`Array<String>`, `paths` relative to `root`),
+      #   `"unmet_pairs"` (`Array<String>`, form pairs no corpus member meets),
+      #   `"single_carrier_pairs"` (`Array<String>`, pairs only one form name
+      #   meets), `"skipped"` (`Array<String>`, paths that could not be
+      #   censused, with the error), `"recent_bugs"` (`bug_titles`), and
+      #   `"covered"` (`Hash{String => Array<String>}`, pair to every form name
+      #   that meets it)
       def brief(paths, root:, bug_titles:)
         covered = Hash.new { |hash, key| hash[key] = [] }
         skipped = []
@@ -66,6 +89,16 @@ module Hecks
           "skipped" => skipped, "recent_bugs" => bug_titles, "covered" => covered }
       end
 
+      # Fills `PROMPT_TEMPLATE`'s `{{placeholders}}` with `brief`'s own data, for
+      # the agent to answer by writing candidate bluebooks.
+      #
+      # @param root [String] repository root the prompt template is read from
+      # @param brief [Hash] the mechanical brief, as returned by `#brief`
+      # @param count [Integer] how many candidates the prompt asks the agent for
+      # @param out_dir [String] where the prompt asks the agent to write candidates
+      # @return [String] the filled-in prompt text
+      # @raise [KeyError] if the template names a placeholder `substitutions` does
+      #   not provide
       def prompt(root, brief, count:, out_dir:)
         substitutions = {
           "count" => count.to_s, "out_dir" => out_dir, "forms" => brief["forms"].join(", "),
@@ -78,6 +111,11 @@ module Hecks
 
       # The second, narrower ask: these candidates did not boot, here is
       # why, fix them in place. Nothing else in the directory changes.
+      #
+      # @param failures [Array<Array(Hash, String)>] `[candidate, error]` pairs,
+      #   `candidate` as returned by `#candidates`, `error` the boot failure message
+      # @param out_dir [String] the directory the candidates were written under
+      # @return [String] the repair round's own prompt text
       def repair_prompt(failures, out_dir:)
         listed = failures.map { |candidate, error| "- #{candidate[:bluebook]}\n  boot error: #{error}" }.join("\n")
         <<~PROMPT
@@ -93,6 +131,11 @@ module Hecks
       # `<out_dir>/<slug>/<anything>.bluebook` plus an optional
       # HYPOTHESIS.md beside it. One bluebook per candidate: the first,
       # alphabetically, if an agent wrote more.
+      #
+      # @param out_dir [String] the directory candidates were written under
+      # @return [Array<Hash>] one `{slug:, dir:, bluebook:, hypothesis:}` entry per
+      #   candidate subdirectory that declares a `.bluebook` file; `hypothesis` is
+      #   `nil` when no `HYPOTHESIS.md` sits beside it
       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
@@ -107,12 +150,28 @@ module Hecks
       # 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.
+      #
+      # @param candidate_dir [String] path to the candidate's own directory
+      # @param covered [Hash{String => Array<String>}] the corpus's own covered
+      #   pairs, as returned in `#brief`'s `"covered"` entry
+      # @return [Array<String>] form pairs the candidate meets that `covered` does
+      #   not already name, sorted
       def new_pairs(candidate_dir, covered)
         FormCensus.covered_pairs(FormCensus.census(candidate_dir)).keys.reject { |pair| covered.key?(pair) }.sort
       end
 
+      # Renders a path relative to the repository root.
+      #
+      # @param path [String] an absolute (or `root`-prefixed) path
+      # @param root [String] the prefix to strip
+      # @return [String] `path` with `root`'s own prefix removed
       def relative(path, root) = path.delete_prefix("#{root}/")
 
+      # Renders a list of strings as a Markdown bullet list.
+      #
+      # @param items [Array<String>] lines to render as a Markdown bullet list
+      # @return [String] one `"- item"` line per entry, newline-joined; `"(none)"`
+      #   when `items` is empty
       def bulleted(items) = items.empty? ? "(none)" : items.map { |item| "- #{item}" }.join("\n")
     end
   end