hecks 3.6.0 → 3.9.0

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

@@ -0,0 +1,138 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Property: what a read-model ask composes from its references.
+      #
+      # Leans on `AggregationRecompute`'s own field-reading and foreign-key helpers, which
+      # `InvariantsAndAggregation` already extends into `Properties`.
+      module ReadModels
+        # Every composed read-model ask answered the heads its references name.
+        #
+        # Each head's rows are recomputed from the instances as the ask saw them: the root is the
+        # record the reference names, a many-side head holds the records whose foreign key points at
+        # it, and a rootless model reads every record. A model's filtering options apply only to the
+        # heads they target. A head with no direct foreign key to the root is inconclusive, and a
+        # model that groups, reduces or scopes by tenant is checked by its own properties.
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true, or a message naming each head that composed otherwise
+        def read_model_heads_compose_from_references(history)
+          bluebooks = history.fetch(:bluebooks, {})
+          offenders = Array(history[:queries]).flat_map { |ask| composition_offenders(ask, bluebooks) }
+          offenders.empty? || offenders.uniq.join("; ")
+        end
+
+        def composition_offenders(ask, bluebooks)
+          bluebook, model = composed_read_model(ask, bluebooks)
+          return [] unless model
+
+          answer = ask[:rows].first || {}
+          offenders = model.aggregate_heads.filter_map { |head| head_offender(bluebook, model, head, ask) }
+          offenders + unexpected_heads(ask[:query], model, answer)
+        end
+
+        # The `[bluebook, read_model]` a successful bare-domain ask named; nil when out of scope.
+        def composed_read_model(ask, bluebooks)
+          return unless answered_read_model_ask?(ask)
+
+          domain, name = ask[:query].split(".", 2)
+          bluebook = bluebooks[domain]
+          model = bluebook&.read_model(name)
+          [bluebook, model] if model && composable?(model)
+        end
+
+        # A bare-domain ask (no `::`, so a read model, not an aggregate query) that was answered.
+        def answered_read_model_ask?(ask)
+          query = ask[:query]
+          query.is_a?(String) && !query.include?("::") && !ask[:error] && ask[:rows].is_a?(Array)
+        end
+
+        def composable?(model)
+          !model.reducing? && model.group_by.empty? && !model.authorization&.tenant
+        end
+
+        def unexpected_heads(query, model, answer)
+          declared = model.aggregate_heads.map { |head| head[:as] }.sort
+          return [] if answer.keys.sort == declared
+
+          ["#{query} answered heads #{answer.keys.sort.inspect}, but declares #{declared.inspect}"]
+        end
+
+        def head_offender(bluebook, model, head, ask)
+          expected = expected_head_states(bluebook, model, head, ask)
+          return unless expected
+
+          answered = answered_ids(head, (ask[:rows].first || {})[head[:as]])
+          problem = head_problem(model, head, expected, [answered, ask[:args]])
+          "#{ask[:query]} head #{head[:as]}: #{problem}" if problem
+        end
+
+        def answered_ids(head, answer)
+          rows = head[:many] ? answer.to_a : [answer].compact
+          rows.map { |row| row[:id].to_s }
+        end
+
+        # The states a head should hold before any option applies, sorted by id; nil when the head
+        # has no direct foreign key to the root, which this property cannot read.
+        def expected_head_states(bluebook, model, head, ask)
+          prefix = "#{bluebook.name}::#{head[:aggregate]}#"
+          states = ask[:instances_at].filter_map { |key, state| state.merge(id: key.split("#").last) if key.start_with?(prefix) }
+          held = candidate_states(bluebook, model, head, states, ask[:args])
+          held&.sort_by { |state| state[:id].to_s }
+        end
+
+        def candidate_states(bluebook, model, head, states, args)
+          return states if model.reference_target.nil?
+
+          reference_id = args[model.reference_name].to_s
+          return states.select { |state| state[:id].to_s == reference_id } if head[:aggregate] == model.reference_target
+
+          referencing_states(bluebook, model, head, states, reference_id)
+        end
+
+        # The states whose foreign key holds the reference; nil when the head has no such key.
+        def referencing_states(bluebook, model, head, states, reference_id)
+          aggregate = bluebook.aggregate(head[:aggregate])
+          fields = aggregate ? foreign_key_fields(aggregate, model) : []
+          states.select { |state| fields.any? { |field| state[field].to_s == reference_id } } unless fields.empty?
+        end
+
+        # `asked` is the answered ids and the ask's arguments, which a `where` value may read.
+        def head_problem(model, head, expected, asked)
+          answered, args = asked
+          return exact_problem(expected, answered) unless model.filtered_head_names.include?(head[:as])
+
+          scoped_problem(model.options_for(head[:as]), expected, answered, args)
+        end
+
+        # An untargeted head holds exactly the states the references name, in any order.
+        def exact_problem(expected, answered)
+          ids = expected.map { |state| state[:id].to_s }
+          return if answered.sort == ids.sort
+
+          "answered #{answered.inspect}, but the references compose #{ids.inspect}"
+        end
+
+        # A targeted head holds the states its `where` clauses admit; `order_by` only reorders them
+        # and a `limit` or `offset` can only narrow them.
+        def scoped_problem(options, expected, answered, args)
+          kept = expected.select { |state| options.wheres.all? { |clause| head_clause_holds?(clause, state, args) } }
+          return exact_problem(kept, answered) unless options.limit || options.offset
+
+          narrowed_problem(kept.map { |state| state[:id].to_s }, answered)
+        end
+
+        def narrowed_problem(admitted, answered)
+          return if (answered - admitted).empty? && answered.size <= admitted.size
+
+          "answered #{answered.inspect}, beyond what its where clauses admit #{admitted.inspect}"
+        end
+
+        # Named for heads: `query_rows.rb` already owns `clause_holds?` in this namespace.
+        def head_clause_holds?(clause, state, args)
+          Ports::Query::InMemory.holds?(clause, comparable_field(state, clause.field), args)
+        end
+      end
+    end
+  end
+end

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

@@ -25,7 +25,17 @@ pre_push:
   checks:
     - id: rspec
       title: rspec (parallel)
-      run: [bundle, exec, parallel_rspec, spec, -n, "{workers}"]
+      run:
+        - sh
+        - -ec
+        - |
+          # Workers are grouped by this machine's own last timings, kept under the git directory
+          # (shared by every worktree, never committed). CI's committed baseline leaves out the io
+          # specs this run includes, so it only seeds the first run; each run then rewrites the log.
+          log="$(git rev-parse --git-common-dir)/hecks_rspec_runtime.log"
+          [ -f "$log" ] || cp .github/rspec_runtime_baseline.log "$log"
+          bundle exec parallel_rspec spec -n {workers} --group-by runtime --runtime-log "$log" --allowed-missing 100 \
+            -o "--format ParallelTests::RSpec::RuntimeLogger --out $log"
       blocked: the suite is red.
     - &check_fuzzing
       id: fuzzing
@@ -114,7 +124,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 }