hecks 2.9.0 → 3.0.1

data/lib/hecks/fuzzing/shrinker.rb

@@ -0,0 +1,166 @@
+module Hecks
+  module Fuzzing
+    # Shrinks a failing step list to a small one that still reproduces the finding.
+    # The caller's block decides "same finding"; this module never replays anything.
+    #
+    # Pass 1 removes step chunks (delta debugging) until the list is 1-minimal.
+    # Pass 2 drops argument keys one at a time inside each surviving step.
+    # `budget:` caps candidate checks; when spent, the best candidate so far is returned.
+    module Shrinker
+      Result = Struct.new(:steps, :attempts, :exhausted, keyword_init: true)
+
+      module_function
+
+      # Shrinks `steps` to the smallest list the block still accepts as reproducing.
+      #
+      # @param steps [Array<Hash>] the step list to shrink
+      # @param budget [Integer, nil] maximum candidate checks to spend; nil for unbounded
+      # @yieldparam candidate [Array<Hash>] a step-dropped or argument-trimmed copy of `steps`
+      # @yieldreturn [Boolean] true if `candidate` still reproduces the finding
+      # @return [Fuzzing::Shrinker::Result] `steps:` the shrunk list, `attempts:` checks
+      #   spent, `exhausted:` whether the budget ran out
+      # @raise [ArgumentError] if no block is given
+      def call(steps, budget: nil, &reproduces)
+        raise ArgumentError, "Shrinker.call needs a block answering whether a candidate reproduces" unless reproduces
+
+        meter   = Meter.new(budget)
+        current = drop_steps(steps.dup, meter, &reproduces)
+        current = drop_arguments(current, meter, &reproduces)
+        Result.new(steps: current, attempts: meter.used, exhausted: meter.exhausted?)
+      end
+
+      def drop_steps(steps, meter, &reproduces)
+        current = steps
+        chunk = [current.length / 2, 1].max
+        loop do
+          changed = false
+          index = 0
+          while index < current.length
+            return current if meter.exhausted?
+
+            candidate = current[0...index] + (current[(index + chunk)..] || [])
+            if candidate.empty?
+              index += chunk
+              next
+            end
+
+            if meter.try { reproduces.call(candidate) }
+              current = candidate
+              changed = true
+            else
+              index += chunk
+            end
+          end
+
+          if chunk > 1
+            chunk = [chunk / 2, 1].max
+          elsif !changed
+            break
+          end
+        end
+        current
+      end
+
+      def drop_arguments(steps, meter, &reproduces)
+        steps.each_index do |position|
+          original = args_of(steps[position])
+          next unless original.is_a?(Hash)
+
+          original.each_key do |key|
+            return steps if meter.exhausted?
+
+            step      = steps[position]
+            trimmed   = args_of(step).reject { |name, _| name == key }
+            candidate = steps.map(&:dup)
+            candidate[position] = step.merge("args" => trimmed)
+            steps = candidate if meter.try { reproduces.call(candidate) }
+          end
+        end
+        steps
+      end
+
+      # `key?` first, never `||`, which cannot tell a stored `false` from an absent key.
+      def args_of(step)
+        step.key?("args") ? step["args"] : step[:args]
+      end
+
+      LIST_FIELDS = %w[refusals queries dry_runs reactions].freeze
+
+      CRASH_FIELDS = %w[crash process generator_crash].freeze
+
+      # The identity a shrink candidate has to keep, as a set of stable strings.
+      #
+      # `field` alone is too loose for list comparisons: a candidate could show a different
+      # refusal split and the shrinker would hand back the wrong bug. So list fields add the
+      # verbs in the symmetric difference, `instances` adds the differing aggregates, and
+      # crash fields add the exception class.
+      #
+      # @param divergences [Array<Hash>] entries carrying at least `{field:, detail:}`
+      # @return [Set<String>] identity strings
+      def signature(divergences)
+        divergences.each_with_object(Set.new) do |divergence, keys|
+          field = divergence[:field].to_s
+          keys << field
+          keys.merge(detail_keys(field, divergence))
+        end
+      end
+
+      def detail_keys(field, divergence)
+        left, right = divergence.except(:field, :detail).values.select { |v| v.is_a?(Array) || v.is_a?(Hash) }
+        if LIST_FIELDS.include?(field) then list_keys(field, left, right)
+        elsif field == "instances"     then instance_keys(left, right)
+        elsif CRASH_FIELDS.include?(field) && divergence[:detail]
+          ["#{field}:#{divergence[:detail].to_s[/\A\w+(?:::\w+)*/]}"]
+        else []
+        end
+      end
+
+      def list_keys(field, left, right)
+        return [] unless left.is_a?(Array) && right.is_a?(Array)
+
+        ((left - right) + (right - left)).map { |row| "#{field}:#{named(row)}" }
+      end
+
+      # The `#id` suffix is dropped: the generator mints ids, so they name the record,
+      # not the finding, and keeping them would pin every creating step.
+      def instance_keys(left, right)
+        return [] unless left.is_a?(Hash) && right.is_a?(Hash)
+
+        (left.keys | right.keys).reject { |key| left[key] == right[key] }
+                                .map { |key| "instances:#{key.to_s.split('#').first}" }
+      end
+
+      # True when the candidate's signature contains the original's.
+      # Removing steps may add a second divergence but must never lose the one being shrunk.
+      def reproduces?(original_signature, divergences)
+        !divergences.empty? && original_signature.subset?(signature(divergences))
+      end
+
+      def named(row)
+        return row.to_s unless row.is_a?(Hash)
+
+        key = [%w[verb query policy], %i[verb query policy]].flatten.find { |name| row.key?(name) }
+        (key ? row[key] : row).to_s
+      end
+
+      # Counts candidate checks against the budget.
+      class Meter
+        attr_reader :used
+
+        # @param budget [Integer, nil] maximum candidate checks to allow; nil for unbounded
+        def initialize(budget)
+          @budget = budget
+          @used   = 0
+        end
+
+        def exhausted? = !@budget.nil? && @used >= @budget
+
+        # Spends one check against the budget and yields.
+        def try
+          @used += 1
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/structural_skips.rb

@@ -0,0 +1,33 @@
+module Hecks
+  module Fuzzing
+    # Names the construct family behind each query verb the Ruby/Rust comparison skipped.
+    # The construct is read from the binary's manifest entry, not guessed from the declaration.
+    module StructuralSkips
+      module_function
+
+      # Attributes each skipped verb to the construct family its manifest entry names.
+      # A verb the manifest does not declare answers `unknown`, which no boundary admits.
+      #
+      # @param gaps [Fuzzing::RustGapManifest] the binary's not-generated manifest entries
+      # @param verbs [Array<String>] the skipped query/read-model verbs to attribute
+      # @return [Array<Hash{Symbol => Object}>] one `{ verb:, constructs: }` per verb,
+      #   sorted by verb
+      def attribute(gaps, verbs)
+        verbs.sort.map do |verb|
+          entry = gaps.not_generated(verb)
+          { verb: verb, constructs: entry ? [entry.fetch("construct")] : %w[unknown] }
+        end
+      end
+
+      # Selects the attributed entries whose constructs are not all inside `boundary`.
+      #
+      # @param attributed [Array<Hash{Symbol => Object}>] entries as returned by `attribute`
+      # @param boundary [Array<String, Symbol>] the construct families the codegen boundary admits
+      # @return [Array<Hash{Symbol => Object}>] the entries naming an unadmitted construct
+      def outside_boundary(attributed, boundary)
+        admitted = boundary.map(&:to_s)
+        attributed.select { |entry| entry[:constructs].empty? || (entry[:constructs] - admitted).any? }
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/sweep_depth.rb

@@ -0,0 +1,43 @@
+module Hecks
+  module Fuzzing
+    # Maps a QA target's clean streak to how hard the next sweep fuzzes.
+    module SweepDepth
+      module_function
+
+      # Fallback tiers for a ledger with no QualityControlDials configured.
+      DEFAULT_TIERS = [
+        { upto: 4,               seeds: 10, steps: 25 },
+        { upto: 19,              seeds: 25, steps: 50 },
+        { upto: Float::INFINITY, seeds: 50, steps: 100 }
+      ].freeze
+
+      # Rows are read in order; the last row must keep upto: Float::INFINITY.
+      def for_streak(streak, tiers: DEFAULT_TIERS)
+        raise ArgumentError, "streak must not be negative" if streak.negative?
+
+        tier = tiers.find { |row| streak <= row[:upto] }
+        raise ArgumentError, "no tier covers a streak of #{streak} — the last row must be upto: Float::INFINITY" unless tier
+
+        [tier[:seeds], tier[:steps]]
+      end
+
+      # The first seed a streak-widened sweep counts from. Once a target's streak has widened past
+      # the ceiling tier, `for_streak` keeps returning the same seed count forever; sweeping
+      # `1..seeds` every time would regenerate the identical sequences on every tick. Advancing
+      # this with the streak keeps the swept range moving into seed integers no earlier tick of
+      # this streak ever reached, without a new persisted field: `streak` already ties consecutive
+      # tiers' ranges back to back (each tier's width times its own streak count), and a streak
+      # reset (back to 0) lands this back at 0 too, so a fresh or just-released target still sweeps
+      # the familiar `1..seeds`.
+      #
+      # @param streak [Integer] `Target#clean_streak`, non-negative
+      # @param seeds [Integer] the seed count `for_streak` resolved for this same streak
+      # @return [Integer] the offset; the sweep should cover `(offset + 1)..(offset + seeds)`
+      def seed_offset(streak, seeds)
+        raise ArgumentError, "streak must not be negative" if streak.negative?
+
+        streak * seeds
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/target_capabilities.rb

@@ -0,0 +1,163 @@
+module Hecks
+  module Fuzzing
+    # Infers what a sweep target can be checked for from its directory, not a stored list.
+    # `modes_to_run = enabled ∩ eligible`: `infer` finds capabilities, `resolve` applies it.
+    module TargetCapabilities
+      module_function
+
+      # Matches the `[features]` table only, so `[package] name = "rust"` never reads as a feature.
+      FEATURES_TABLE = /^\[features\](?:\n(?!\[).*)*$/
+
+      # Both spellings: aggregate-scoped `.persisted_by("PostgresEra")` and the bare
+      # domain-level `persisted_by "PostgresEra"`.
+      POSTGRES_ERA_BINDING = /persisted_by\s*\(?\s*"PostgresEra"/
+
+      # A local assigned the bare literal on its own line; any other right-hand side is not one.
+      POSTGRES_ERA_VARIABLE = /^\s*([a-z_]\w*)\s*=\s*"PostgresEra"\s*(?:#.*)?$/
+
+      # Captures the member a hecksagon attaches; authorization is read off its declaration.
+      FRAMEWORK_ATTACHED = /uses_framework\s*\(?\s*"([^"]+)"/
+
+      # A command-level `role "..."`, the only construct a role check can compare a caller against.
+      ROLE_GATED = /^\s*role\s+"/
+
+      TENANT_SCOPED = /\btenant:/
+
+      PROCESS_MANAGER = /^\s*process_manager\s+"/
+
+      # Capabilities each mode needs; an empty list means any target.
+      # `resolve` drops `ruby_only` when `differential` resolves too: same seat, Rust is better.
+      MODE_REQUIREMENTS = {
+        differential:               %w[rust],
+        ruby_only:                  [],
+        self_consistency:           [],
+        properties_in_differential: %w[rust],
+        structural_skip_report:     %w[rust],
+        adapter_parity_sqlite:      %w[sqlite],
+        persistence_parity:         %w[postgres_era],
+        adapter_parity_postgres:    %w[postgres_era],
+        era_boundary:               %w[translations postgres_era],
+        concurrency:                %w[postgres_era],
+        wasm_front:                 %w[rust]
+      }.freeze
+
+      # The modes `hecks quality_control ask run` can run; one absent here is refused at start, not
+      # resolved.
+      RUNNABLE_MODES = %i[differential ruby_only self_consistency properties_in_differential
+                          structural_skip_report adapter_parity_sqlite persistence_parity
+                          era_boundary concurrency].freeze
+
+      # Expensive passes run only when named (`--modes`) or as `--all`'s second wave.
+      DEFERRED_MODES = %i[persistence_parity adapter_parity_postgres era_boundary concurrency].freeze
+
+      # Reads a target directory to find out which capabilities it actually has.
+      #
+      # @param domain_path [String] filesystem path to the target domain's directory
+      # @param rust_dir [String] path to the Rust project root, checked for a matching
+      #   Cargo feature; defaults to this repo's own `rust/` directory
+      # @return [Array<String>] the target's capabilities, sorted; a subset of
+      #   `sqlite`, `rust`, `postgres_era`, `translations`, `governance`, `role_gated`,
+      #   `tenant`, `sagas`
+      def infer(domain_path, rust_dir: File.expand_path("../../../rust", __dir__))
+        capabilities = %w[sqlite]
+        capabilities << "rust" if rust_feature?(domain_path, rust_dir)
+        capabilities << "postgres_era" if postgres_era_bound?(domain_path)
+        capabilities << "translations" if Dir.glob(File.join(domain_path, "**", "translations", "*.bluebook")).any?
+        capabilities << "governance" if authorization_attached?(domain_path)
+        capabilities << "role_gated" if any_file?(domain_path, "*.bluebook", ROLE_GATED)
+        capabilities << "tenant" if any_file?(domain_path, "*.bluebook", TENANT_SCOPED)
+        capabilities << "sagas" if any_file?(domain_path, "*.bluebook", PROCESS_MANAGER)
+        capabilities.sort
+      end
+
+      # Answers whether `mode` can run against a target with `capabilities`.
+      #
+      # @param mode [Symbol, String] a key of `MODE_REQUIREMENTS`, such as `:differential`
+      # @param capabilities [Array<String>] the target's capabilities, as `infer` returns
+      # @return [Boolean] whether `capabilities` covers every capability `mode` requires
+      # @raise [ArgumentError] if `mode` names no entry in `MODE_REQUIREMENTS`
+      def eligible?(mode, capabilities)
+        required = MODE_REQUIREMENTS.fetch(mode.to_sym) { raise ArgumentError, "unknown sweep mode #{mode.inspect}" }
+        (required - capabilities).empty?
+      end
+
+      # Filters the enabled modes down to those the target is eligible for, keeping their order.
+      #
+      # @param enabled [Array<Symbol, String>] modes turned on, in the dial's own
+      #   declaration order
+      # @param capabilities [Array<String>] the target's capabilities, as `infer` returns
+      # @return [Array<Symbol>] `enabled`'s eligible modes, in `enabled`'s order, with
+      #   `:ruby_only` dropped whenever `:differential` is also eligible
+      def resolve(enabled, capabilities)
+        resolved = enabled.map(&:to_sym).select { |mode| eligible?(mode, capabilities) }
+        resolved.delete(:ruby_only) if resolved.include?(:differential)
+        resolved
+      end
+
+      # Answers whether `rust_dir`'s Cargo.toml declares a feature named after
+      # `domain_path`'s own directory.
+      #
+      # @param domain_path [String] filesystem path to the target domain's directory;
+      #   its basename, lowercased, is the feature name looked up
+      # @param rust_dir [String] path to the Rust project root (holds `Cargo.toml`)
+      # @return [Boolean] whether a matching Cargo feature is declared; false if
+      #   `rust_dir` has no `Cargo.toml`
+      def rust_feature?(domain_path, rust_dir)
+        cargo_toml = File.join(rust_dir, "Cargo.toml")
+        return false unless File.file?(cargo_toml)
+
+        feature  = File.basename(domain_path).downcase
+        features = File.read(cargo_toml)[FEATURES_TABLE] || ""
+        features.match?(/^#{Regexp.escape(feature)}\s*=\s*\[\]/)
+      end
+
+      # Answers whether any `.hecksagon` under `domain_path` binds PostgresEra,
+      # by literal name or through a local variable assigned `"PostgresEra"`.
+      #
+      # @param domain_path [String] filesystem path to the target domain's directory
+      # @return [Boolean] whether a PostgresEra `persisted_by` binding is found
+      def postgres_era_bound?(domain_path)
+        Dir.glob(File.join(domain_path, "**", "*.hecksagon")).any? do |path|
+          text = File.read(path)
+          text.match?(POSTGRES_ERA_BINDING) || postgres_era_variable_bound?(text)
+        end
+      end
+
+      # Answers whether `text` passes a variable assigned `"PostgresEra"` to `persisted_by`.
+      #
+      # @param text [String] the contents of one `.hecksagon` file
+      # @return [Boolean] whether some `persisted_by` call names such a variable
+      def postgres_era_variable_bound?(text)
+        text.scan(POSTGRES_ERA_VARIABLE).flatten.any? do |name|
+          text.match?(/persisted_by\s*\(?\s*#{Regexp.escape(name)}(?!\w)/)
+        end
+      end
+
+      # Answers whether any `.hecksagon` under `domain_path` attaches a member
+      # that provides authorization.
+      #
+      # The capability label stays "governance" because it is the value stored in the ledger.
+      #
+      # @param domain_path [String] filesystem path to the target domain's directory
+      # @return [Boolean] whether the domain attaches a member that provides the
+      #   `Bluebook::Capabilities::AUTHORIZATION` capability
+      def authorization_attached?(domain_path)
+        attached = Dir.glob(File.join(domain_path, "**", "*.hecksagon"))
+                      .flat_map { |path| File.read(path).scan(FRAMEWORK_ATTACHED).flatten }.uniq
+        providers = Framework.providers_of(Bluebook::Capabilities::AUTHORIZATION)
+        attached.intersect?(providers)
+      end
+
+      # Answers whether any file under `domain_path` matching `glob` contains `pattern`.
+      #
+      # @param domain_path [String] filesystem path to the target domain's directory
+      # @param glob [String] a `Dir.glob` pattern relative to `domain_path`, such as
+      #   `"*.bluebook"`
+      # @param pattern [Regexp] the pattern each matching file's contents is tested against
+      # @return [Boolean] whether any matching file's contents match `pattern`
+      def any_file?(domain_path, glob, pattern)
+        Dir.glob(File.join(domain_path, "**", glob)).any? { |path| File.read(path).match?(pattern) }
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/value_generator.rb

@@ -0,0 +1,216 @@
+require_relative "../runtime/value"
+
+module Hecks
+  module Fuzzing
+    # Generates one JSON-safe value per attribute, in the shape the hand-written corpus uses.
+    # Edge cases are frequent but not dominant; name-aware shapes reach deep state.
+    module ValueGenerator
+      module_function
+
+      EDGE_CASE_PROBABILITY = 0.2
+      INVALID_MEMBER_PROBABILITY = 0.1
+      INVALID_REFERENCE_PROBABILITY = 0.2
+      # Exercises the bare-scalar form a single-field value object accepts.
+      BARE_SCALAR_PROBABILITY = 0.2
+
+      STRING_EDGE_CASES = [
+        "", "x", "with \"quotes\"", "with, a comma", "with a \\backslash",
+        "unicode héllo wörld 🎉", "x" * 200, "  leading and trailing  "
+      ].freeze
+      # Includes Bignums past i64, which a Rust kernel value cannot represent (`kernel/json.rs`).
+      INTEGER_EDGE_CASES = [0, -1, 2_147_483_647, -2_147_483_648, 2**100, -(2**100)].freeze
+      # Clock- and count-shaped fields stay under f64's exact-integer ceiling: `Json::Num` is an
+      # f64, so a Bignum there only re-hits the known precision-loss class.
+      SAFE_INTEGER_EDGE_CASES = [0, -1, 2_147_483_647, -2_147_483_648].freeze
+      # Tested against the value object's name plus the attribute's name; deliberately narrow, so
+      # "amount"/"cents"/"sequence" keep the full Bignum pool.
+      CLOCK_OR_COUNT_NAME_PATTERN = /clock|instant|expir|ttl|\bnow\b|timestamp|epoch|count/i
+      # NaN and infinities are safe to generate; -0.0 covers signed zero.
+      FLOAT_EDGE_CASES = [0.0, -0.0, -0.5, -100.25, Float::NAN, Float::INFINITY, -Float::INFINITY].freeze
+      WORDS = %w[alpha bravo charlie delta echo foxtrot golf hotel india juliet].freeze
+      CURRENCY_CODES = %w[USD EUR GBP JPY].freeze
+
+      # The value for one command/query/value-object attribute.
+      #
+      # `context` carries the enclosing value object's name, since `EmailAddress`'s `address` field
+      # only looks email-shaped through the name of the object around it.
+      #
+      # @param attribute [Bluebook::Attribute] the attribute to generate a value for
+      # @param aggregate [Bluebook::Aggregate] the aggregate `attribute` belongs to
+      # @param random [Random] the RNG driving every draw this call makes
+      # @param known_ids [Hash{String => Array<String>}] real ids by aggregate or entity name
+      # @param context [String, nil] the enclosing value object's name; nil at the top level
+      # @return [String, Integer, Float, Boolean, Hash] a JSON-safe value: a nested Hash for a
+      #   value-object type, a bare id String for a reference, a primitive otherwise
+      def value_for(attribute, aggregate, random:, known_ids: {}, context: nil)
+        return reference_value(attribute, random: random, known_ids: known_ids) if attribute.reference?
+
+        # Same lookup the runtime uses: an identity value object may live on a sibling aggregate.
+        value_object = Runtime::Value.value_object_for(aggregate, attribute.type.to_s)
+        return object_for(value_object, aggregate, random: random, known_ids: known_ids) if value_object
+
+        primitive(attribute.type.to_s, random: random, name: "#{context} #{attribute.name}")
+      end
+
+      # Generates a nested value for a whole value object: a random admitted
+      # row for a closed set, or a value per declared attribute otherwise —
+      # occasionally unwrapped to a bare scalar for a genuinely single-field
+      # value object.
+      #
+      # @param value_object [Bluebook::ValueObject] the value object to generate a value for
+      # @param aggregate [Bluebook::Aggregate] the aggregate `value_object` is reached from
+      # @param random [Random] the RNG driving every draw this call makes
+      # @param known_ids [Hash{String => Array<String>}] real ids by aggregate or entity name
+      # @return [Hash, Object] `{field name => value, ...}`, or the lone value when the
+      #   value object has one field and the bare-scalar draw hits
+      def object_for(value_object, aggregate, random:, known_ids:)
+        fields =
+          if value_object.closed_set? && !value_object.members.empty?
+            return invalid_member(value_object, random: random) if random.rand < INVALID_MEMBER_PROBABILITY
+
+            member = value_object.members.sample(random: random)
+            member.to_h { |field, value| [field.to_s, value] }
+          else
+            value_object.attributes.to_h do |field|
+              [field.name.to_s,
+               value_for(field, aggregate, random: random, known_ids: known_ids, context: value_object.hecks_name)]
+            end
+          end
+
+        # Unwrap only a genuinely single-field value object, never `invalid_member`: a wrong
+        # combination stays a Hash so its wrongness is what gets exercised.
+        return fields.values.first if fields.size == 1 && random.rand < BARE_SCALAR_PROBABILITY
+
+        fields
+      end
+
+      # A combination that (almost certainly) isn't one of the closed set's admitted rows,
+      # to exercise the refusal a `one_of` exists to enforce.
+      #
+      # @param value_object [Bluebook::ValueObject] the closed-set value object to
+      #   generate a non-admitted combination for
+      # @param random [Random] the RNG driving every draw this call makes
+      # @return [Hash] `{field name => value, ...}` for every declared attribute, each
+      #   drawn independently rather than sampled from an admitted row
+      def invalid_member(value_object, random:)
+        value_object.attributes.to_h do |field|
+          [field.name.to_s, primitive(field.type.to_s, random: random, name: field.name.to_s)]
+        end
+      end
+
+      # The ID itself, unwrapped: the payload gate refuses `{"value" => id}` for a reference.
+      #
+      # @param attribute [Bluebook::Attribute] the reference-typed attribute to
+      #   generate a value for
+      # @param random [Random] the RNG driving every draw this call makes
+      # @param known_ids [Hash{String => Array<String>}] known real ids, keyed by
+      #   aggregate or entity name; looked up under `attribute.type.target_name`
+      # @return [String] a real id drawn from the matching pool most of the time; a
+      #   fabricated `"missing-..."` id when the pool is empty or the invalid-reference
+      #   draw hits
+      def reference_value(attribute, random:, known_ids:)
+        pool = known_ids[attribute.type.target_name.to_s] || []
+        return "missing-#{random.bytes(4).unpack1('H*')}" if pool.empty? || random.rand < INVALID_REFERENCE_PROBABILITY
+
+        pool.sample(random: random)
+      end
+
+      # Generates a value for one Ruby-primitive-typed attribute.
+      #
+      # @param type_name [String] the primitive type name: `"String"`, `"Integer"`,
+      #   `"Float"`, `"Boolean"`, `"TrueClass"`, or `"FalseClass"`
+      # @param random [Random] the RNG driving every draw this call makes
+      # @param name [String, nil] a name hint (attribute name, optionally
+      #   context-prefixed) that draws an email-/currency-shaped string or a
+      #   clock/count-shaped integer
+      # @return [String, Integer, Float, Boolean] a value of the type `type_name` names
+      # @raise [ArgumentError] if `type_name` names anything else
+      def primitive(type_name, random:, name: nil)
+        case type_name
+        when "String"  then string_value(random, name: name)
+        when "Integer" then integer_value(random, name: name)
+        when "Float"   then float_value(random)
+        when "TrueClass", "FalseClass", "Boolean" then random.rand(2).zero?
+        else raise ArgumentError, "ValueGenerator does not know primitive type #{type_name.inspect}"
+        end
+      end
+
+      # Generates a String value, name-aware for shapes an invariant needs (email, currency).
+      #
+      # @param random [Random] the RNG driving every draw this call makes
+      # @param name [String, nil] a name hint; an `"email"` or `"currency"` match
+      #   draws a shaped value instead of random words
+      # @return [String] an edge-case string, an email address, a currency code, or
+      #   1-3 random words joined by spaces
+      def string_value(random, name: nil)
+        return STRING_EDGE_CASES.sample(random: random) if random.rand < EDGE_CASE_PROBABILITY
+        return email_value(random) if name&.match?(/email/i)
+        return CURRENCY_CODES.sample(random: random) if name&.match?(/currency/i)
+
+        Array.new(random.rand(1..3)) { WORDS.sample(random: random) }.join(" ")
+      end
+
+      # Generates a fabricated, syntactically valid email address.
+      #
+      # @param random [Random] the RNG driving every draw this call makes
+      # @return [String] a `"word@word.example"` address
+      def email_value(random)
+        "#{WORDS.sample(random: random)}@#{WORDS.sample(random: random)}.example"
+      end
+
+      # Generates an Integer value, skewed positive so `positive?`-style invariants are reachable.
+      # Zero and negatives still come through the edge-case pool.
+      #
+      # @param random [Random] the RNG driving every draw this call makes
+      # @param name [String, nil] a name hint; a clock/count-shaped match narrows
+      #   the edge-case pool to `SAFE_INTEGER_EDGE_CASES`
+      # @return [Integer] an edge-case integer sometimes, else a random count in 1..1000
+      def integer_value(random, name: nil)
+        if random.rand < EDGE_CASE_PROBABILITY
+          pool = clock_or_count_shaped?(name) ? SAFE_INTEGER_EDGE_CASES : INTEGER_EDGE_CASES
+          return pool.sample(random: random)
+        end
+
+        random.rand(1..1000)
+      end
+
+      # Reports whether a field name reads as a clock reading or a policy-capped count.
+      #
+      # @param name [String, nil] the name to test
+      # @return [Boolean] true if `name` matches the clock/count name pattern
+      def clock_or_count_shaped?(name)
+        name.to_s.match?(CLOCK_OR_COUNT_NAME_PATTERN)
+      end
+
+      # Generates a Float value.
+      #
+      # @param random [Random] the RNG driving every draw this call makes
+      # @return [Float] an edge-case float sometimes, else a random value in
+      #   0.01..1000.0, rounded to 2 decimal places
+      def float_value(random)
+        return FLOAT_EDGE_CASES.sample(random: random) if random.rand < EDGE_CASE_PROBABILITY
+
+        random.rand(0.01..1000.0).round(2)
+      end
+
+      # The bare scalar a generated identity value stands for, for recording into `known_ids`.
+      # A reference to this record is already that scalar; the two are not interchangeable.
+      #
+      # @param identity_value [Hash, Object] a generated identity value, as `value_for`
+      #   produced it — a Hash for a multi-field value object, or the bare scalar already
+      #   for a single-field one
+      # @return [String] the identity's bare scalar, stringified
+      def scalar_of(identity_value)
+        identity_value.is_a?(Hash) ? identity_value.values.first.to_s : identity_value.to_s
+      end
+
+      # Generates a fabricated id unrelated to anything `known_ids` tracks.
+      #
+      # @param random [Random] the RNG driving every draw this call makes
+      # @return [String] a `"gen-"`-prefixed id with 8 random hex characters
+      def random_id(random)
+        "gen-#{random.bytes(4).unpack1('H*')}"
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing.rb

@@ -0,0 +1,23 @@
+module Hecks
+  # The fuzzing toolkit hecks fuzz and hecks generate_sequence drive. Not required by
+  # lib/hecks.rb on purpose — a booted domain never needs it.
+  module Fuzzing
+  end
+end
+
+require_relative "fuzzing/value_generator"
+require_relative "fuzzing/invalid_value_generator"
+require_relative "fuzzing/sequence_generator"
+require_relative "fuzzing/nondeterministic"
+require_relative "fuzzing/replay"
+require_relative "fuzzing/shrinker"
+require_relative "fuzzing/properties"
+require_relative "fuzzing/qa_settings"
+require_relative "fuzzing/rotation_priority"
+require_relative "fuzzing/sweep_depth"
+require_relative "fuzzing/persistence_parity"
+require_relative "fuzzing/form_census"
+require_relative "fuzzing/target_capabilities"
+require_relative "fuzzing/rust_gap_manifest"
+require_relative "fuzzing/structural_skips"
+require_relative "fuzzing/coverage_campaign"