hecks 3.6.0 → 3.7.0

data/lib/hecks/fuzzing/properties/role_checks.rb

@@ -0,0 +1,50 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Property: the role check at dispatch agrees with the grants the replay itself made.
+      #
+      # `CommandRules::Authorization` asks the authorization provider whether an identified caller
+      # holds a command's role, through the `assignments` verb the provider's chapter declares with
+      # `provides "authorization"`. Each `history[:role_checks]` entry carries the grants read back
+      # through that same verb before the dispatch, so the answer is recomputed from them.
+      module RoleChecks
+        # How `Replay.refusal_kind` names the refusal the role gate raises.
+        UNAUTHORIZED = "Hecks::Runtime::Unauthorized".freeze
+
+        # An identified caller holding a live grant of the role is never refused as unauthorized,
+        # and one holding none is never accepted.
+        #
+        # A refusal other than Unauthorized proves nothing about the grant: argument gates run
+        # before the role gate, so an ungranted caller can be turned away for another reason first.
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true, or a message naming each dispatch the grants contradict
+        def role_checks_agree_with_grants(history)
+          offenders = Array(history[:role_checks]).filter_map { |check| role_check_offender(check) }
+          offenders.empty? || offenders.uniq.join("; ")
+        end
+
+        # A message when `check`'s outcome contradicts its grants; nil when consistent or unclear.
+        def role_check_offender(check)
+          held = role_held?(check)
+          return refused_message(check) if held && check[:outcome] == UNAUTHORIZED
+
+          accepted_message(check) if !held && check[:outcome].nil?
+        end
+
+        def role_held?(check)
+          check[:grants].any? { |grant| grant[:role] == check[:role] && !grant[:ended] }
+        end
+
+        def refused_message(check)
+          "#{check[:verb]} was refused as unauthorized for #{check[:actor_id]}, who holds a live grant of " \
+            "#{check[:role].inspect}"
+        end
+
+        def accepted_message(check)
+          "#{check[:verb]} was accepted for #{check[:actor_id]}, who holds no live grant of #{check[:role].inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/properties.rb

@@ -13,7 +13,11 @@ require_relative "properties/corrections"
 require_relative "properties/outbox"
 require_relative "properties/policy_wiring"
 require_relative "properties/references"
+require_relative "properties/role_checks"
+require_relative "properties/read_model_names"
+require_relative "properties/read_models"
 require_relative "properties/catalog"
+require_relative "properties/guaranteed_by_construction"
 
 module Hecks
   module Fuzzing
@@ -32,6 +36,9 @@ module Hecks
       extend Outbox
       extend PolicyWiring
       extend References
+      extend RoleChecks
+      extend ReadModelNames
+      extend ReadModels
 
       module_function
 

data/lib/hecks/fuzzing/replay/observation.rb

@@ -10,7 +10,7 @@ module Hecks
           { instances: Replay.snapshot_instances(@runtime), events: events, refusals: @refusals,
             reactions: @runtime.reactions, sagas: @runtime.sagas, saga_instances: saga_instances,
             queries: @queries, dry_runs: @dry_runs, dry_run_traces: @dry_run_traces,
-            fan_outs: @fan_outs, guard_checks: @guard_checks,
+            fan_outs: @fan_outs, guard_checks: @guard_checks, role_checks: @role_checks,
             mutation_traces: @mutation_traces, outbox_traces: @outbox_traces,
             saga_dispatches: @runtime.saga_dispatches, policy_dispatches: @runtime.policy_dispatches,
             bluebook: @runtime.registry.bluebooks.values.first,

data/lib/hecks/fuzzing/replay/role_check.rb

@@ -0,0 +1,49 @@
+module Hecks
+  module Fuzzing
+    module Replay
+      # Reads, before a role-gated dispatch by an identified caller, the grants that actor holds
+      # through the authorization provider's own declared `assignments` verb, so the outcome can be
+      # compared with what the dispatch actually did.
+      module RoleCheck
+        module_function
+
+        # The caller and live grants for one step; nil for any step with no identified caller, no
+        # declared role, or no authorization provider (those compare role strings, not grants).
+        #
+        # @param runtime [Hecks::Runtime] the booted runtime the step will dispatch against
+        # @param step [Hash] a replay step, string-keyed
+        # @return [Hash, nil] `verb:`, `role:`, `actor_id:` and `grants:` (each `role:`, `ended:`)
+        def build(runtime, step)
+          return nil unless step["role"] && step["actor_id"]
+
+          domain, command = command_of(runtime, step["verb"])
+          return nil unless command && governed?(runtime, domain, command)
+
+          { verb: step["verb"], role: command.role.to_s, actor_id: step["actor_id"].to_s,
+            grants: grants_for(runtime.registry, step["actor_id"]) }
+        rescue StandardError
+          nil
+        end
+
+        # The `[domain, command]` an aggregate-level verb names; the command is nil when none does.
+        def command_of(runtime, verb)
+          domain, aggregate_name, command_name = Naming.split_verb(verb)
+          [domain, runtime.registry.bluebook(domain)&.aggregate(aggregate_name)&.command(command_name)]
+        end
+
+        # Whether the command declares a role and its domain has an authorization provider.
+        def governed?(runtime, domain, command)
+          !command.role.to_s.empty? && !runtime.registry.authorization_provider_for(domain).nil?
+        end
+
+        # The actor's assignments, read through the verb the provider declares for `assignments`.
+        def grants_for(registry, actor_id)
+          provider = registry.authorization_providers.first
+          verb = provider.provided_verb(Bluebook::Capabilities::AUTHORIZATION, :assignments)
+          rows = Runtime::Dispatcher.new(registry).query(verb, actor_id: { value: actor_id.to_s })
+          rows.map { |row| { role: row[:role_name][:value], ended: !row[:ends_at].nil? } }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/replay/session.rb

@@ -18,7 +18,7 @@ module Hecks
         # `outbox_ids` is a set of delivery_ids, not a size, because `runtime.outbox.rows`
         # concatenates several stores' own arrays, so a plain "grew from N to M" tail slice
         # could miss or misattribute rows once more than one repository has an outbox.
-        Marks = Struct.new(:reaction, :saga, :outbox_ids, :fan_out_snapshot, :guard_check, :mutation_trace)
+        Marks = Struct.new(:reaction, :saga, :outbox_ids, :fan_out_snapshot, :guard_check, :mutation_trace, :role_check)
 
         # @param runtime [Hecks::Runtime] a freshly booted runtime
         def initialize(runtime)
@@ -28,7 +28,7 @@ module Hecks
           @dry_runs        = []
           @dry_run_traces  = []
           @fan_outs        = []
-          @guard_checks    = []
+          start_checks
           @mutation_traces = []
           @outbox_traces   = []
           @fan_out_targets = fan_out_targets
@@ -61,6 +61,12 @@ module Hecks
 
         private
 
+        # The two checks recorded before a dispatch and compared with its outcome afterwards.
+        def start_checks
+          @guard_checks = []
+          @role_checks  = []
+        end
+
         def play_step(step)
           step = step.transform_keys(&:to_s)
           args = (step["args"] || {}).transform_keys(&:to_sym)
@@ -84,7 +90,7 @@ module Hecks
           result = Replay.as_step_caller(step) { @runtime.dispatch_flat(step["verb"], args) }
           record_effects(step, result, marks)
         rescue *Runtime::DOMAIN_REFUSALS, Bluebook::Expression::EvaluationError => e
-          record_refusal(step, e, marks&.guard_check)
+          record_refusal(step, e, marks&.guard_check, marks&.role_check)
         end
 
         # Taken before dispatch, so this step's own reactions, sagas and outbox rows can be
@@ -98,17 +104,23 @@ module Hecks
         def take_marks(step, args)
           Marks.new(@runtime.reactions.size, @runtime.sagas.size, @runtime.outbox.rows.map(&:delivery_id),
                     fan_out_snapshot, GuardCheck.build(@runtime, step["verb"], args),
-                    MutationTrace.build(@runtime, step["verb"], args))
+                    MutationTrace.build(@runtime, step["verb"], args), RoleCheck.build(@runtime, step))
         end
 
         def record_effects(step, result, marks)
           @fan_outs.concat(Replay.fan_out_findings(@runtime, marks.fan_out_snapshot, result.events,
                                                    @runtime.reactions[marks.reaction..]))
           record_outbox(step, marks)
-          @guard_checks << marks.guard_check.merge(actual_refused: false, actual_kind: nil) if marks.guard_check
+          record_accepted_checks(marks)
           record_mutation(marks.mutation_trace) if marks.mutation_trace
         end
 
+        # An accepted dispatch: the guard let it through and the role gate did not refuse it.
+        def record_accepted_checks(marks)
+          @guard_checks << marks.guard_check.merge(actual_refused: false, actual_kind: nil) if marks.guard_check
+          @role_checks << marks.role_check.merge(outcome: nil) if marks.role_check
+        end
+
         # Every outbox row this step's own dispatch newly wrote, across every
         # bound repository including any a reaction cascade touched, paired with
         # the reaction/saga rows that same dispatch produced. Skipped when empty.
@@ -139,8 +151,12 @@ module Hecks
         # Only a refusal raised by the guard itself counts for the guard check. A refusal from a
         # stage before or after enforce_givens can share TypeMismatch's class, so
         # anything outside the two guard classes is left out — inconclusive, not a pass.
-        def record_refusal(step, error, guard_check)
+        #
+        # A role check records the refusal's class whatever it is, since the property decides which
+        # outcomes are conclusive: a refusal before the role gate says nothing about the grant.
+        def record_refusal(step, error, guard_check, role_check)
           @refusals << { verb: step["verb"], error: error.message, kind: Replay.refusal_kind(error) }
+          @role_checks << role_check.merge(outcome: Replay.refusal_kind(error)) if role_check
           return unless guard_check && GUARD_REFUSAL_CLASSES.include?(error.class)
 
           @guard_checks << guard_check.merge(actual_refused: true, actual_kind: error.class.name)

data/lib/hecks/fuzzing/replay.rb

@@ -5,6 +5,7 @@ require_relative "self_consistency"
 require_relative "replay/filters"
 require_relative "replay/fan_out"
 require_relative "replay/guard_check"
+require_relative "replay/role_check"
 require_relative "replay/mutation_trace"
 require_relative "replay/session"
 

data/lib/hecks/fuzzing/runtime_coverage.rb

@@ -0,0 +1,70 @@
+module Hecks
+  module Fuzzing
+    # Measures which lines (and, when stdlib Coverage is running, branches) of the Ruby runtime a
+    # block reaches, as a set of stable "path:line" and "path:line:branch" strings.
+    #
+    # Lines come from a TracePoint, so code that was loaded before the measurement still counts.
+    # Branches need stdlib Coverage started before the code was loaded; when it is not running, the
+    # measurement is lines only.
+    #
+    # Pure observation: nothing here draws a random number, so a seed's keys are as reproducible
+    # as the seed.
+    module RuntimeCoverage
+      module_function
+
+      # @param roots [Array<String>] directories whose files count; anything else is ignored
+      # @yield the work to measure
+      # @return [Array(Object, Set<String>)] the block's value and the keys it reached
+      def measure(roots: default_roots, &block)
+        raise ArgumentError, "RuntimeCoverage.measure needs a block" unless block
+
+        prefixes = roots.map { |root| File.join(File.expand_path(root), "") }
+        reached = Set.new
+        before = branch_snapshot
+        value = trace_lines(prefixes, reached, &block)
+        reached.merge(branch_keys(before, branch_snapshot, prefixes))
+        [value, reached]
+      end
+
+      # The runtime this gem ships, the default measurement scope.
+      def default_roots = [File.expand_path("..", __dir__)]
+
+      def trace_lines(prefixes, reached)
+        value = nil
+        tracer = TracePoint.new(:line) do |point|
+          path = point.path
+          reached << "#{path}:#{point.lineno}" if in_roots?(path, prefixes)
+        end
+        tracer.enable { value = yield }
+        value
+      end
+
+      # @return [Hash, nil] Coverage's branch table so far (files that report branches), or nil
+      #   when Coverage is not running
+      def branch_snapshot
+        return unless defined?(::Coverage) && ::Coverage.respond_to?(:running?) && ::Coverage.running?
+
+        ::Coverage.peek_result.filter_map { |path, entry| [path, entry[:branches]] if entry.is_a?(Hash) && entry[:branches] }.to_h
+      end
+
+      # Branch targets whose hit count grew between two snapshots.
+      def branch_keys(before, after, prefixes)
+        return [] unless before && after
+
+        after.select { |path, _branches| in_roots?(path, prefixes) }.flat_map do |path, branches|
+          grown(before[path] || {}, branches).map { |key| "#{path}:#{key}" }
+        end
+      end
+
+      def in_roots?(path, prefixes) = prefixes.any? { |prefix| path.start_with?(prefix) }
+
+      def grown(old, new)
+        new.flat_map do |origin, targets|
+          targets.filter_map do |target, count|
+            "#{origin.drop(1).join(":")}:#{target.drop(1).join(":")}" if count > (old.dig(origin, target) || 0)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/shrinker/value_simplification.rb

@@ -0,0 +1,64 @@
+module Hecks
+  module Fuzzing
+    module Shrinker
+      # Pass 3 of the shrinker: offers each surviving argument value a simpler stand-in and keeps
+      # the ones the finding survives. Split out of `Shrinker` so each file holds one idea.
+      module ValueSimplification
+        module_function
+
+        # Offers each surviving argument a simpler value, keeping one the finding survives. Nested
+        # hashes are simplified key by key; a candidate that stops reproducing is rejected.
+        def call(steps, meter, &)
+          steps.each_index do |position|
+            original = Shrinker.args_of(steps[position])
+            next unless original.is_a?(Hash)
+
+            original.each_key do |key|
+              steps = simplify_path(steps, position, [key], meter, &)
+            end
+          end
+          steps
+        end
+
+        # Simplifies the value at `path` inside step `position`'s arguments, recursing into hashes.
+        def simplify_path(steps, position, path, meter, &)
+          value = Shrinker.args_of(steps[position]).dig(*path)
+          if value.is_a?(Hash)
+            return value.each_key.reduce(steps) { |acc, key| simplify_path(acc, position, path + [key], meter, &) }
+          end
+
+          simpler_values(value).each do |replacement|
+            return steps if meter.exhausted?
+
+            candidate = with_value(steps, position, path, replacement)
+            return candidate if meter.try { yield(candidate) }
+          end
+          steps
+        end
+
+        # Simpler stand-ins for `value`, simplest first; none for what is already minimal.
+        def simpler_values(value)
+          candidates =
+            case value
+            when String  then ["", value[0].to_s]
+            when Integer then [0, 1]
+            when Float   then [0.0, 1.0]
+            when Array   then [[], value.first(1)]
+            else []
+            end
+          candidates.uniq.reject { |candidate| candidate == value }
+        end
+
+        def with_value(steps, position, path, replacement)
+          step = steps[position]
+          args = Marshal.load(Marshal.dump(Shrinker.args_of(step)))
+          parent = path.length > 1 ? args.dig(*path[0...-1]) : args
+          parent[path.last] = replacement
+          candidate = steps.map(&:dup)
+          candidate[position] = step.merge("args" => args)
+          candidate
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/shrinker.rb

@@ -5,6 +5,8 @@ module Hecks
     #
     # 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.
+    # Pass 3 replaces each surviving argument value with a simpler one (empty, zero, first
+    # element) wherever the finding still reproduces, so a repro reads as small as it is.
     # `budget:` caps candidate checks; when spent, the best candidate so far is returned.
     module Shrinker
       Result = Struct.new(:steps, :attempts, :exhausted, keyword_init: true)
@@ -26,6 +28,7 @@ module Hecks
         meter   = Meter.new(budget)
         current = drop_steps(steps.dup, meter, &reproduces)
         current = drop_arguments(current, meter, &reproduces)
+        current = ValueSimplification.call(current, meter, &reproduces)
         Result.new(steps: current, attempts: meter.used, exhausted: meter.exhausted?)
       end
 

data/lib/hecks/fuzzing.rb

@@ -11,6 +11,7 @@ require_relative "fuzzing/sequence_generator"
 require_relative "fuzzing/nondeterministic"
 require_relative "fuzzing/replay"
 require_relative "fuzzing/shrinker"
+require_relative "fuzzing/shrinker/value_simplification"
 require_relative "fuzzing/properties"
 require_relative "fuzzing/qa_settings"
 require_relative "fuzzing/rotation_priority"
@@ -20,4 +21,6 @@ require_relative "fuzzing/form_census"
 require_relative "fuzzing/target_capabilities"
 require_relative "fuzzing/rust_gap_manifest"
 require_relative "fuzzing/structural_skips"
+require_relative "fuzzing/runtime_coverage"
 require_relative "fuzzing/coverage_campaign"
+require_relative "fuzzing/failure_triage"

data/lib/hecks/gate/stages.yml

@@ -114,7 +114,7 @@ ci:
       run: [bundle, exec, exe/hecks, fuzz_run.fuzz, adapter=sqlite, seeds=6, --wait]
       blocked: the SQLite adapter broke a property the Memory adapter held; seeds are 1..N, so the run repeats.
     - id: fuzz_postgres
-      title: fuzz on real Postgres, one worker (every ephemeral boot recreates the same scratch schema)
+      title: fuzz on real Postgres, up to four workers (each in its own scratch schema)
       run: [bundle, exec, exe/hecks, fuzz_run.fuzz, adapter=postgres, seeds=3, steps=20, --wait]
       blocked: the Postgres adapter broke a property the Memory adapter held; it needs PGHOST, PGUSER and PGPASSWORD.
     - id: vocabulary_drift

data/lib/hecks/hecks/adapters/deploy_toolchain/answers.rb

@@ -89,9 +89,10 @@ module Hecks
         end
 
         # What the script would overwrite, read from the script itself (its schemas and databases).
+        # Its schemas are the default of the `SCHEMAS=${SCHEMAS:-"..."}` line (overridable).
         def copy_plan(script, held)
           text = File.read(script)
-          schemas = text[/^SCHEMAS="([^"]*)"/, 1].to_s.split.join(", ")
+          schemas = text[/^SCHEMAS=(?:\$\{SCHEMAS:-)?"([^"]*)"/, 1].to_s.split.join(", ")
           source_db, target_db = copy_databases(text, held)
           drop = plain(held[:force]) == true ? "; force=true drops each target schema first" : ""
           "copy schemas #{schemas} from database #{source_db} on #{plain(held[:source])} into database " \

data/lib/hecks/hecks/adapters/github_rulesets.rb

@@ -89,17 +89,19 @@ module Hecks
       end
 
       def compare_checks(projected, live)
-        mine = contexts(projected)
-        theirs = contexts(live)
+        mine = required(projected)
+        theirs = required(live)
         return [] if mine == theirs
 
         ["#{projected["name"]}: required checks are #{theirs.inspect} on GitHub, #{mine.inspect} in the model"]
       end
 
-      # The check names a ruleset's `required_status_checks` rule demands, sorted.
-      def contexts(ruleset)
+      # Each check a ruleset's `required_status_checks` rule demands, as its name and the app id it
+      # must come from (nil when any app may report it), sorted.
+      def required(ruleset)
         rule = Array(ruleset["rules"]).find { |candidate| candidate["type"] == "required_status_checks" }
-        Array(rule&.dig("parameters", "required_status_checks")).map { |check| check["context"] }.sort
+        Array(rule&.dig("parameters", "required_status_checks"))
+          .map { |check| [check["context"], check["integration_id"]] }.sort_by(&:to_s)
       end
 
       def actors(ruleset)

data/lib/hecks/hecks/adapters/process_pool.rb

@@ -32,6 +32,12 @@ module Hecks
       # What the sweep child runs: the `fuzz` tool, which takes the flags that follow.
       ENTRY = 'require "hecks/tools"; Hecks::Tools.script("fuzz", ARGV)'
 
+      # What the mutation child runs: the `mutate` tool, which takes the flags that follow.
+      MUTATE_ENTRY = 'require "hecks/tools"; Hecks::Tools.script("mutate", ARGV)'
+
+      # The flags of a mutation run, and the fields of the record that fill them.
+      MUTATE_FLAGS = { "--seeds" => :seeds, "--steps" => :steps, "--budget" => :budget }.freeze
+
       # Signals passed on to a running child's process group.
       FORWARDED = %w[INT TERM HUP QUIT].freeze
 
@@ -63,6 +69,18 @@ module Hecks
         answer(run([RbConfig.ruby, "-I", LIB, "-e", ENTRY, "--", *sweep_words(held)]))
       end
 
+      # Mutation-tests one domain: changes its rules in small ways and reports each change its
+      # checks let through.
+      #
+      # @param held [Hash] the `Mutating` record: `domain`, `seeds`, `steps`, `budget`
+      # @return [Hash{Symbol => Hash}] `report:` what the run printed
+      # @raise [ConsoleCapture::Failure] when the run could not start
+      def probe(**held)
+        words = [plain(held[:domain]), *flag_words(held, MUTATE_FLAGS)]
+
+        answer(run([RbConfig.ruby, "-I", LIB, "-e", MUTATE_ENTRY, "--", *words]))
+      end
+
       # Starts a child, forwards interrupts to it, and waits for it to end.
       #
       # @param command [Array<String>] the program, then its arguments
@@ -94,12 +112,16 @@ module Hecks
 
       # The words after `--`: the domain when named, then each flag the record names.
       def sweep_words(held)
-        words = []
-        words << plain(held[:domain]) if plain(held[:domain])
-        SWEEP_FLAGS.each { |flag, key| words.push(flag, plain(held[key]).to_s) unless plain(held[key]).nil? }
-        words
+        [*plain(held[:domain]), *flag_words(held, SWEEP_FLAGS), *persist_words(held)]
+      end
+
+      # Each flag whose field the record holds, followed by that field's value.
+      def flag_words(held, flags)
+        flags.flat_map { |flag, key| plain(held[key]).nil? ? [] : [flag, plain(held[key]).to_s] }
       end
 
+      def persist_words(held) = plain(held[:persist_regressions]) == true ? ["--persist-regressions"] : []
+
       # The options a child is spawned with: its own process group, its output in `output`.
       def spawn_options(output, chdir)
         options = { pgroup: true, out: output, err: output }

data/lib/hecks/hecks/custodian.behaviors

@@ -147,6 +147,12 @@ Hecks.behaviors "Custodian" do
     expect refused: "a count is positive"
   end
 
+  test "Mutate refuses a budget that is not positive" do
+    tests "Mutate", on: "FuzzRun"
+    input run: { value: "mutants" }, domain: { value: "examples/pizzas" }, budget: { value: 0 }
+    expect refused: "a count is positive"
+  end
+
   test "Fuzz refuses a persistence it does not know" do
     tests "Fuzz", on: "FuzzRun"
     input run: { value: "sweep" }, adapter: { value: "cassandra" }

data/lib/hecks/hecks/custodian.bluebook

@@ -1963,7 +1963,9 @@ policy "RecordTheEra" do
     attribute :seeds,      Count,       optional: true
     attribute :steps,      Count,       optional: true
     attribute :workers,    Count,       optional: true
+    attribute :budget,     Count,       optional: true
     attribute :adapter,    Persistence, optional: true
+    attribute :persist_regressions, RegressionSwitch, optional: true
     attribute :domains,    NameList,    optional: true
     attribute :targets,    NameList,    optional: true
     attribute :iterations, Count,       optional: true
@@ -2006,6 +2008,11 @@ policy "RecordTheEra" do
       attribute :value, String, pattern: '^(memory|sqlite|postgres)$'
     end
 
+    # Whether each distinct finding's minimized repro is also kept under `spec/corpus/regressions/`.
+    value_object "RegressionSwitch" do
+      attribute :value, Boolean
+    end
+
     # Names, comma separated: benchmark domains, or the targets to measure.
     value_object "NameList" do
       attribute :value, String, pattern: '^[^ \t\n\r,]+(,[^ \t\n\r,]+)*$'
@@ -2047,6 +2054,7 @@ policy "RecordTheEra" do
       attribute :steps,   Count,       optional: true
       attribute :workers, Count,       optional: true
       attribute :adapter, Persistence, optional: true
+      attribute :persist_regressions, RegressionSwitch, optional: true
 
       sets :domain
       sets :run
@@ -2054,10 +2062,34 @@ policy "RecordTheEra" do
       sets :steps
       sets :workers
       sets :adapter
+      sets :persist_regressions
 
       emits FuzzRequested
     end
 
+    # Mutation-tests a domain's own checks: changes its bluebooks in small ways and keeps which
+    # changes the fuzz properties, the corpus script and the domain's behaviors tests let through.
+    # A survivor is a hole in those checks. `budget` caps how many mutants are tried. The run is a
+    # child process started through the ProcessPool adapter, as a sweep is.
+    command "Mutate" do
+      role "Operator"
+      goal "Mutate a domain's rules and keep whether its checks noticed each change"
+
+      attribute :domain, DomainPath
+      attribute :run,    FuzzKey
+      attribute :seeds,  Count, optional: true
+      attribute :steps,  Count, optional: true
+      attribute :budget, Count, optional: true
+
+      sets :domain
+      sets :run
+      sets :seeds
+      sets :steps
+      sets :budget
+
+      emits MutateRequested
+    end
+
     # Measures each persistence adapter, and the Rust binary when there is one to build or use.
     # The report is kept in this record, which the Hecks domain binds to Memory: keeping a
     # domain's benchmark history beside it, in Sqlite under the project's `.hecks/`, is decided
@@ -2148,6 +2180,11 @@ policy "RecordTheEra" do
     trigger FuzzRun::ProcessPool::Sweep, with: { run: :run }
   end
 
+  policy "MutateWhenRequested" do
+    on      "FuzzRun.MutateRequested"
+    trigger FuzzRun::ProcessPool::Probe, with: { run: :run }
+  end
+
   policy "MeasureWhenRequested" do
     on      "FuzzRun.BenchRequested"
     trigger FuzzRun::RustToolchain::Measure, with: { run: :run }

data/lib/hecks/hecks/hecks.hecksagon

@@ -188,6 +188,12 @@ Hecks.hecksagon "Hecks" do
       answers "FuzzAnswered"
       refuses "FuzzRefused"
     end
+
+    asks "Probe", to: FuzzRun do
+      attribute :run, FuzzKey
+      answers "FuzzAnswered"
+      refuses "FuzzRefused"
+    end
   end
 
   Hecks::FuzzRun.port "RustToolchain" do

data/lib/hecks/language/bluebook/vocabulary.bluebook

@@ -706,6 +706,8 @@ Hecks.bluebook "Bluebook" do
              meaning: "Fraction (0.0..1.0) of seeds that start from a prefix of an earlier seed's new coverage. Off by default: measured, it trades breadth for depth (banking reached 1.41x the deep-state tuples, chess lost 0.12x of all tuples), while favoring rare verbs alone never lost."
       member name: "favor_rare_verbs", type: "Integer",
              meaning: "How many of the least-hit verbs the next seed weights up; 0 turns the lever off."
+      member name: "runtime_coverage_feedback", type: "Boolean",
+             meaning: "Whether guided generation also admits a seed to the corpus for reaching a new line or branch of the Ruby runtime (`Hecks::Fuzzing::RuntimeCoverage`), not only a new (verb, kind, state, mutation, outcome) tuple. Off by default: tracing every line slows each seed."
       member name: "self_consistency_checks", type: "Boolean",
              meaning: "Whether `hecks quality_control query sweep.run` also runs the self-consistency pass (cold rehydration, replay idempotency, value-object JSON round trip) on the same generated sequence."
       member name: "shrink_budget", type: "Integer",
@@ -802,6 +804,7 @@ Hecks.bluebook "Bluebook" do
       member script: "fuzz", section: "Custodian", aggregate: "FuzzRun", verb: "fuzz"
       member script: "generate", section: "Custodian", aggregate: "FuzzRun", verb: "generate_sequence"
       member script: "bench", section: "Custodian", aggregate: "FuzzRun", verb: "bench"
+      member script: "(new)", section: "Custodian", aggregate: "FuzzRun", verb: "mutate"
       member script: "(new)", section: "Custodian", aggregate: "Era", verb: "hold_first"
       member script: "project_deploy", section: "Deploy", aggregate: "Recipe", verb: "project"
       member script: "lint_deploy_recipes", section: "Deploy", aggregate: "MakefileCheck", verb: "lint"

data/lib/hecks/projections/deploy/box/roll_scripts.rb

@@ -44,7 +44,8 @@ module Hecks
             template("deploy-box.sh.tmpl", "STACK" => plan.infra_name, "BOX_STACK" => plan.box_stack,
                                            "RDS_STACK" => plan.rds_stack, "REGION" => region,
                                            "DIR" => "/opt/#{plan.infra_name}", "HEALTH_CHECKS" => health_checks(plan),
-                                           "SMOKE_HEADER" => smoke_header(plan), "USAGE" => deploy_usage(plan))
+                                           "SMOKE_HEADER" => smoke_header(plan), "USAGE" => deploy_usage(plan),
+                                           "DB_SECRET_LINE" => database_secret_line(plan))
           end
 
           # @param plan [Settings::Plan] the resolved settings
@@ -96,9 +97,10 @@ module Hecks
           # @return [String] a Makefile whose targets create the two stacks and roll the box
           def makefile(plan)
             hint = plan.task_definition ? "[TASKDEF=family:revision]" : '[TAGS="web=20260101 worker=20260101"]'
-            base = template("Makefile.tmpl", "STACK" => plan.infra_name, "DEPLOY_HINT" => hint,
-                                             "RDS_STACK" => plan.rds_stack, "BOX_STACK" => plan.box_stack,
-                                             "DEPLOY_RECIPE" => RollRecipe.deploy(plan))
+            base = template("Makefile.tmpl", { "STACK" => plan.infra_name, "DEPLOY_HINT" => hint,
+                                               "RDS_STACK" => plan.rds_stack, "BOX_STACK" => plan.box_stack,
+                                               "DEPLOY_RECIPE" => RollRecipe.deploy(plan) }
+                                               .merge(database_makefile_values(plan)))
             plan.hosting ? "#{base}\ninclude hosting.mk\n" : base
           end
 

data/lib/hecks/projections/deploy/box/settings/patterns.rb

@@ -23,6 +23,10 @@ module Hecks
             S3_BUCKET   = /\A[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]\z/
             S3_SHAPE    = "s3_access: a list of `{ bucket: \"name\", write: true }` hashes (write is optional)".freeze
             FROM_TASKDEF = %i[env secrets repository].freeze
+
+            # The settings that size an RDS instance: with `shared_database` they are the shared
+            # instance's.
+            SHARED_INSTANCE_SETTINGS = %i[database_class storage_gb engine_version backup_days].freeze
             # Default images, each a version tag plus the digest of its multi-architecture index,
             # so a rebuilt box pulls the same bytes.
             TUNNEL_IMAGE = "cloudflare/cloudflared:2026.9.3" \