hecks 3.6.0 → 3.9.0

data/lib/hecks/fuzzing/form_census/reference_forms.rb

@@ -0,0 +1,49 @@
+module Hecks
+  module Fuzzing
+    module FormCensus
+      # The reference-hop forms: a path crossing references, and a reference re-declared under
+      # another type. Each reads one aggregate's exported hash.
+      module ReferenceForms
+        # A given path crossing two references has at least this many segments.
+        TWO_HOP_GIVEN_PATH_LENGTH = 3
+
+        module_function
+
+        def two_hop_given?(aggregate)
+          FormCensus.commands(aggregate).any? do |verb|
+            (verb["givens"] || []).any? { |given| deep_lookup?(given["ast"]) }
+          end
+        end
+
+        # A `where` whose field crosses two `/` hops, as in `member/sponsor/standing`.
+        def multi_hop_where?(aggregate)
+          FormCensus.queries(aggregate).any? do |query|
+            (query["wheres"] || []).any? { |where| where["field"].to_s.count("/") >= 2 }
+          end
+        end
+
+        # A command attribute reusing the name of a reference attribute under a non-reference type.
+        def revalued_reference?(aggregate)
+          references = FormCensus.attributes(aggregate).select { |held| FormCensus.reference?(held) }
+                                 .to_set { |held| held["name"].to_s }
+          FormCensus.commands(aggregate).any? do |verb|
+            (verb["attributes"] || []).any? { |held| references.include?(held["name"].to_s) && !FormCensus.reference?(held) }
+          end
+        end
+
+        def deep_lookup?(node)
+          case node
+          when Hash
+            return true if node["op"] == "lookup" && Array(node["path"]).size >= TWO_HOP_GIVEN_PATH_LENGTH
+
+            node.each_value.any? { |child| deep_lookup?(child) }
+          when Array
+            node.any? { |child| deep_lookup?(child) }
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/form_census.rb

@@ -1,5 +1,7 @@
 require "json"
 require_relative "../corpus"
+require_relative "form_census/chapter_forms"
+require_relative "form_census/reference_forms"
 
 module Hecks
   module Fuzzing
@@ -9,9 +11,6 @@ module Hecks
     # they cannot drift. The unit is one aggregate: forms on one head meet at dispatch, forms in one
     # chapter do not.
     module FormCensus
-      # A given path crossing two references has at least this many segments.
-      TWO_HOP_GIVEN_PATH_LENGTH = 3
-
       # Ports and adapters a census boots with, relative to the repository root.
       CENSUS_SUPPORT = [
         "lib/hecks/ports/persistence.port", "lib/hecks/ports/extraction.port",
@@ -19,25 +18,28 @@ module Hecks
       ].freeze
 
       FORMS = {
-        "composite_id"       => ->(a) { (a["identified_by"] || []).size >= 2 },
-        "has_entity"         => ->(a) { entities(a).any? },
-        "two_entities"       => ->(a) { entities(a).size >= 2 },
-        "composite_piece"    => ->(a) { entities(a).any? { |piece| (piece["identified_by"] || []).size >= 2 } },
-        "multi_emit"         => ->(a) { commands(a).any? { |verb| (verb["emits"] || []).size >= 2 } },
-        "lifecycle"          => ->(a) { !a["lifecycle"].nil? },
-        "piece_lifecycle"    => ->(a) { entities(a).any? { |piece| !piece["lifecycle"].nil? } },
-        "has_query"          => ->(a) { queries(a).any? },
-        "list_attr"          => ->(a) { attributes(a).any? { |held| held["list"] } },
-        "reference_attr"     => ->(a) { attributes(a).any? { |held| reference?(held) } },
-        "closed_set"         => ->(a) { (a["value_objects"] || []).any? { |shape| shape["closed_set"] } },
-        "has_default"        => ->(a) { attributes(a).any? { |held| !held["default"].nil? } },
-        "has_optional"       => ->(a) { commands(a).any? { |verb| (verb["attributes"] || []).any? { |held| held["optional"] } } },
+        "composite_id"          => ->(a) { (a["identified_by"] || []).size >= 2 },
+        "has_entity"            => ->(a) { entities(a).any? },
+        "two_entities"          => ->(a) { entities(a).size >= 2 },
+        "composite_piece"       => ->(a) { entities(a).any? { |piece| (piece["identified_by"] || []).size >= 2 } },
+        "multi_emit"            => ->(a) { commands(a).any? { |verb| (verb["emits"] || []).size >= 2 } },
+        "lifecycle"             => ->(a) { !a["lifecycle"].nil? },
+        "piece_lifecycle"       => ->(a) { entities(a).any? { |piece| !piece["lifecycle"].nil? } },
+        "has_query"             => ->(a) { queries(a).any? },
+        "list_attr"             => ->(a) { attributes(a).any? { |held| held["list"] } },
+        "reference_attr"        => ->(a) { attributes(a).any? { |held| reference?(held) } },
+        "closed_set"            => ->(a) { (a["value_objects"] || []).any? { |shape| shape["closed_set"] } },
+        "has_default"           => ->(a) { attributes(a).any? { |held| !held["default"].nil? } },
+        "has_optional"          => ->(a) { optional_command_attribute?(a) },
         # Reference-hop forms, then `corrects` and `role`; entity commands count too.
-        "corrects"           => ->(a) { every_command(a).any? { |verb| corrects?(verb) } },
-        "role_gated"         => ->(a) { every_command(a).any? { |verb| !verb["role"].to_s.empty? } },
-        "two_hop_given"      => ->(a) { two_hop_given?(a) },
-        "multi_hop_where"    => ->(a) { multi_hop_where?(a) },
-        "revalued_reference" => ->(a) { revalued_reference?(a) }
+        "corrects"              => ->(a) { every_command(a).any? { |verb| corrects?(verb) } },
+        "role_gated"            => ->(a) { every_command(a).any? { |verb| !verb["role"].to_s.empty? } },
+        "two_hop_given"         => ->(a) { ReferenceForms.two_hop_given?(a) },
+        "multi_hop_where"       => ->(a) { ReferenceForms.multi_hop_where?(a) },
+        "revalued_reference"    => ->(a) { ReferenceForms.revalued_reference?(a) },
+        # Chapter-level constructs, attributed to the aggregate they name (see `ChapterForms`).
+        "cross_domain_policy"   => ->(a) { (a["across_policies"] || []).any? },
+        "multi_head_read_model" => ->(a) { (a["multi_head_read_models"] || []).any? }
       }.freeze
 
       module_function
@@ -51,42 +53,16 @@ module Hecks
 
       def corrects?(verb) = (verb["mutations"] || []).any? { |change| change["op"].to_s == "corrects" }
 
+      def optional_command_attribute?(aggregate)
+        commands(aggregate).any? { |verb| (verb["attributes"] || []).any? { |held| held["optional"] } }
+      end
+
       def attributes(aggregate) = aggregate["attributes"] || []
 
       def queries(aggregate)    = aggregate["queries"] || []
 
       def reference?(attribute) = attribute["type"].to_s.start_with?("Reference<")
 
-      def two_hop_given?(aggregate)
-        commands(aggregate).any? { |verb| (verb["givens"] || []).any? { |given| deep_lookup?(given["ast"]) } }
-      end
-
-      # A `where` whose field crosses two `/` hops, as in `member/sponsor/standing`.
-      def multi_hop_where?(aggregate)
-        queries(aggregate).any? { |query| (query["wheres"] || []).any? { |where| where["field"].to_s.count("/") >= 2 } }
-      end
-
-      # A command attribute reusing the name of a reference attribute under a non-reference type.
-      def revalued_reference?(aggregate)
-        references = attributes(aggregate).select { |held| reference?(held) }.to_set { |held| held["name"].to_s }
-        commands(aggregate).any? do |verb|
-          (verb["attributes"] || []).any? { |held| references.include?(held["name"].to_s) && !reference?(held) }
-        end
-      end
-
-      def deep_lookup?(node)
-        case node
-        when Hash
-          return true if node["op"] == "lookup" && Array(node["path"]).size >= TWO_HOP_GIVEN_PATH_LENGTH
-
-          node.each_value.any? { |child| deep_lookup?(child) }
-        when Array
-          node.any? { |child| deep_lookup?(child) }
-        else
-          false
-        end
-      end
-
       def properties(aggregate)
         FORMS.transform_values { |form| form.call(aggregate) }
       end
@@ -107,7 +83,7 @@ module Hecks
 
       def aggregates_in(chapter_ir)
         (chapter_ir["aggregates"] || []).map do |aggregate|
-          ["#{chapter_ir["name"]}::#{aggregate["name"]}", properties(aggregate)]
+          ["#{chapter_ir["name"]}::#{aggregate["name"]}", properties(ChapterForms.onto(aggregate, chapter_ir))]
         end
       end
 

data/lib/hecks/fuzzing/isolated_boot/postgres_scratch.rb

@@ -3,12 +3,12 @@ module Hecks
     module IsolatedBoot
       # Rebinds a copied domain to a scratch Postgres schema and prepares that schema.
       module PostgresScratch
-        # Rewrites every `.hecksagon` in the copy to bind through Postgres, against the
-        # shared scratch schema unless the caller names its own via `scratch:`.
+        # Rewrites every `.hecksagon` in the copy to bind through Postgres, against this process's
+        # scratch schema unless the caller names its own via `scratch:`.
         def rebind_to_postgres!(copy, database: nil, schema: nil)
           require "pg"
           database ||= FUZZ_POSTGRES_DATABASE
-          schema   ||= FUZZ_POSTGRES_SCHEMA
+          schema   ||= scratch_schema(database)
           rewrite_bindings!(copy, "Postgres")
           strip_translations!(copy)
           ensure_fuzz_schema!(database, schema)
@@ -107,15 +107,30 @@ module Hecks
           reset_schema!(database, schema, create: false)
         end
 
+        # Several pool children may reach this at once: one wins the CREATE, and the rest see the
+        # database exist, or wait out the moment the template database is busy and look again.
         def create_database_if_missing(database)
           admin = PG.connect(dbname: "postgres")
-          exists = admin.exec_params(
-            "SELECT 1 FROM pg_database WHERE datname = $1", [database]
-          ).ntuples.positive?
-          admin.exec(%(CREATE DATABASE "#{database}")) unless exists
+          3.times do
+            break if database_exists?(admin, database)
+
+            create_database(admin, database)
+          end
           admin.close
         end
 
+        def database_exists?(admin, database)
+          admin.exec_params("SELECT 1 FROM pg_database WHERE datname = $1", [database]).ntuples.positive?
+        end
+
+        def create_database(admin, database)
+          admin.exec(%(CREATE DATABASE "#{database}"))
+        rescue PG::DuplicateDatabase, PG::UniqueViolation
+          nil
+        rescue PG::ObjectInUse
+          sleep(0.2)
+        end
+
         # Drops `schema` from `database`, and creates it again when `create` is true.
         def reset_schema!(database, schema, create:)
           db = PG.connect(dbname: database)

data/lib/hecks/fuzzing/isolated_boot/scratch_schema.rb

@@ -0,0 +1,27 @@
+module Hecks
+  module Fuzzing
+    module IsolatedBoot
+      # Which Postgres scratch schema a fuzz boot uses: one per pool child, so children can fuzz
+      # one database at once, or the shared default for any other process.
+      module ScratchSchema
+        # The schema this process boots into. A pool child names its own in `FUZZ_SCHEMA_ENV`, so
+        # several children can fuzz one database at once; it is dropped when the child exits.
+        # Any other process shares `FUZZ_POSTGRES_SCHEMA`, which is safe only one boot at a time.
+        def scratch_schema(database)
+          named = ENV.fetch(FUZZ_SCHEMA_ENV, nil)
+          return FUZZ_POSTGRES_SCHEMA unless named
+
+          @fuzz_schema_cleanups ||= {}
+          @fuzz_schema_cleanups[named] ||= at_exit { drop_schema_quietly(database, named) }
+          named
+        end
+
+        def drop_schema_quietly(database, schema)
+          reset_schema!(database, schema, create: false)
+        rescue PG::Error
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -6,6 +6,7 @@ require_relative "../runtime/adapter_lookup"
 require_relative "isolated_boot/copying"
 require_relative "isolated_boot/worlds"
 require_relative "isolated_boot/postgres_scratch"
+require_relative "isolated_boot/scratch_schema"
 
 module Hecks
   module Fuzzing
@@ -14,14 +15,17 @@ module Hecks
     module IsolatedBoot
       # Postgres has no zero-config default (Postgres.connect_for refuses without a
       # `database` setting), so every domain name gets a fresh `.world` written for it.
-      # One shared schema, dropped and recreated per boot, not a fresh name per call —
-      # safe only because callers run one ephemeral boot at a time.
+      # One schema per process, dropped and recreated per boot, not a fresh name per call —
+      # a process runs one ephemeral boot at a time. The default is shared by every process that
+      # does not name its own schema in `FUZZ_SCHEMA_ENV`, as a sweep's pool children do.
       FUZZ_POSTGRES_DATABASE = "hecks_fuzz".freeze
       FUZZ_POSTGRES_SCHEMA   = "hecks_fuzz".freeze
+      FUZZ_SCHEMA_ENV        = "HECKS_FUZZ_SCHEMA".freeze
 
       extend Copying
       extend Worlds
       extend PostgresScratch
+      extend ScratchSchema
 
       module_function
 

data/lib/hecks/fuzzing/mutation/checks.rb

@@ -0,0 +1,76 @@
+require_relative "../../cli/run"
+require_relative "../../behaviors"
+require_relative "observation"
+
+module Hecks
+  module Fuzzing
+    module Mutation
+      # What is replayed against a domain and its mutants: the generated sequences, the corpus
+      # script and the domain's own `.behaviors` tests.
+      #
+      # @!attribute [r] sequences
+      #   @return [Array<Array<Hash>>] generated step lists, valid for the unmutated domain
+      # @!attribute [r] corpus
+      #   @return [Hash, nil] the parsed corpus script
+      Plan = Struct.new(:sequences, :corpus)
+
+      # The checks a mutant is held to, each answering what it saw.
+      module Checks
+        module_function
+
+        # What the unmutated domain does under the plan, as values a mutant's run is compared to.
+        #
+        # @param domain [String] the domain directory
+        # @param plan [Plan] what to replay
+        # @return [Hash] `:sequences` an observation per sequence, `:corpus` one for the script and
+        #   `:failing_behaviors` the `.behaviors` tests that already fail
+        def baseline(domain, plan)
+          { sequences:         plan.sequences.map { |steps| Observation.of(Replay.call(domain, steps)) },
+            corpus:            plan.corpus && Observation.of(corpus_report(domain, plan.corpus)),
+            failing_behaviors: failing_behaviors(domain) }
+        end
+
+        # @return [String, nil] why the copy cannot boot, nil when it does
+        def boot_failure(copy)
+          Replay.call(copy, [])
+          nil
+        rescue StandardError, ScriptError => e
+          "#{e.class}: #{e.message.lines.first.to_s.strip}"
+        end
+
+        # @return [String, nil] the first property a history breaks, as `property: <name>`
+        def property_failure(history)
+          broken = Properties.check(history).find { |_, result| result != true }
+          broken && "property: #{broken.first}"
+        end
+
+        # The report `hecks run` would print for the script.
+        def corpus_report(domain, corpus)
+          IsolatedBoot.call(domain) do |copy|
+            CLI::Run.execute(Hecks.boot(copy, environment: nil), corpus.fetch("steps"))
+          end
+        end
+
+        # @return [String, nil] the first expectation of the script the report does not meet
+        def unmet_expectation(corpus, report)
+          unmet = CLI::RunExpectations.unmet(corpus["expectations"] || {}, report).first
+          unmet && unmet.lines.first.strip
+        end
+
+        # The `.behaviors` tests of the domain that do not pass, by description.
+        #
+        # @param domain [String] the domain directory
+        # @return [Array<String>] empty when every test passes or the domain has none
+        def failing_behaviors(domain)
+          Behaviors.run_all(domain).files.flat_map { |file| failures_in(file) }
+        end
+
+        def failures_in(file)
+          return ["#{file.path}: #{file.parse_error}"] if file.parse_error
+
+          file.runs.reject { |run| run.status == :pass }.map(&:description)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/mutation/finders.rb

@@ -0,0 +1,136 @@
+module Hecks
+  module Fuzzing
+    module Mutation
+      # Each finder looks at one line of a `SourceMap` and answers the changes that apply there, as
+      # `{ operator:, removed:, replacement: }` hashes; `Operators` turns them into `Site`s.
+      module Finders
+        # The shape of a change: a line (or block) taken out, or a line written differently.
+        module Change
+          module_function
+
+          def removal(operator, length = 1) = { operator: operator, removed: length, replacement: [] }
+
+          def rewrite(operator, line) = { operator: operator, removed: 1, replacement: [line] }
+        end
+
+        # Rules a command or value object enforces: `given`, `invariant`, comparisons, query bounds,
+        # an attribute's `pattern:` and `one_of:`.
+        module Rules
+          RULE = /\A\s*(given|invariant)\b.*\{.*\}\s*\z/
+          COMPARISONS = { " >= " => " > ", " > " => " >= ", " <= " => " < ", " < " => " <= ",
+                          " == " => " != ", " != " => " == " }.freeze
+          PATTERN = /,\s*pattern:\s*'[^']*'/
+          CLOSED_SET = /,\s*one_of:\s*\[[^\]]*\]/
+          BOUND = /\A\s*where\(.*\b(lt|gt):/
+
+          module_function
+
+          def at(map, index)
+            line = map.lines[index]
+            rule(line) + attribute(line) + query_bound(line)
+          end
+
+          def rule(line)
+            return [] unless line.match?(RULE)
+
+            flipped = flip_comparison(line)
+            [Change.removal(:"drop_#{line[RULE, 1]}"), (Change.rewrite(:flip_comparison, flipped) if flipped)].compact
+          end
+
+          # The first comparison inside the line's braces, moved one step.
+          def flip_comparison(line)
+            body = line[/\{.*\}/]
+            operator = COMPARISONS.keys.find { |candidate| body.include?(candidate) }
+            operator && line.sub(body, body.sub(operator, COMPARISONS.fetch(operator)))
+          end
+
+          def attribute(line)
+            return [] unless line.match?(/\A\s*attribute\b/)
+
+            [[:drop_pattern, PATTERN], [:drop_one_of, CLOSED_SET]].filter_map do |operator, shape|
+              (found = line[shape]) && Change.rewrite(operator, line.sub(found, ""))
+            end
+          end
+
+          def query_bound(line)
+            return [] unless line.match?(BOUND)
+
+            [Change.rewrite(:flip_query_bound, line.sub(/\b(lt|gt):/) { Regexp.last_match(1) == "lt" ? "gt:" : "lt:" })]
+          end
+        end
+
+        # The shape of the domain: `from:` guards, `sets`, lifecycle targets, emitted events.
+        module Structure
+          GUARD = /,\s*from:\s*"[^"]*"/
+
+          module_function
+
+          def at(map, index)
+            line = map.lines[index]
+            scope = map.scope(index)
+            sets(line, scope) + command_guard(line) + transition(map, line, scope) + emits(map, line)
+          end
+
+          def sets(line, scope)
+            line.match?(/\A\s*sets\s+:\w+\s*\z/) && scope == "command" ? [Change.removal(:drop_sets)] : []
+          end
+
+          def command_guard(line)
+            guard = line[GUARD]
+            guard && line.match?(/\A\s*command\b.*\bdo\s*\z/) ? [Change.rewrite(:drop_from_guard, line.sub(guard, ""))] : []
+          end
+
+          def transition(map, line, scope)
+            match = line.match(SourceMap::TRANSITION)
+            return [] unless match && scope == "lifecycle"
+
+            [retarget(map, line, match[3]), guard(line, match[4])].compact
+          end
+
+          def retarget(map, line, target)
+            other = map.states.find { |state| state != target }
+            other && Change.rewrite(:retarget_transition, line.sub("=> \"#{target}\"", "=> \"#{other}\""))
+          end
+
+          def guard(line, rest)
+            found = rest[GUARD]
+            found && Change.rewrite(:drop_from_guard, line.sub(found, ""))
+          end
+
+          def emits(map, line)
+            match = line.match(SourceMap::EMITS)
+            other = match && map.emitted.find { |name| name != match[2] }
+            other ? [Change.rewrite(:swap_emits, "#{match[1]}emits #{other}\n")] : []
+          end
+        end
+
+        # Reactions: whole policies, and what a process manager does on each of its transitions.
+        module Reactions
+          module_function
+
+          def at(map, index)
+            line = map.lines[index]
+            scope = map.scope(index)
+            policy(map, index, line) + saga_transition(map, index, line, scope) + saga_dispatch(line, scope)
+          end
+
+          def policy(map, index, line)
+            length = line.match?(/\A\s*policy\s+"/) && map.block_length(index)
+            length ? [Change.removal(:drop_policy, length)] : []
+          end
+
+          def saga_transition(map, index, line, scope)
+            length = scope == "process_manager" && line.match?(/\A\s*transition\b.*\bdo\s*\z/) && map.block_length(index)
+            length ? [Change.removal(:drop_saga_transition, length)] : []
+          end
+
+          def saga_dispatch(line, scope)
+            scope == "transition" && line.match?(/\A\s*dispatch\s+\S/) ? [Change.removal(:drop_saga_dispatch)] : []
+          end
+        end
+
+        ALL = [Rules, Structure, Reactions].freeze
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/mutation/judge.rb

@@ -0,0 +1,94 @@
+require_relative "checks"
+
+module Hecks
+  module Fuzzing
+    module Mutation
+      # How one mutant fared.
+      #
+      # @!attribute [r] site
+      #   @return [Site] what was changed
+      # @!attribute [r] status
+      #   @return [Symbol] `:killed`, `:survived`, `:unreached` or `:invalid`
+      # @!attribute [r] by
+      #   @return [String, nil] what killed it (`property: <name>`, `crash: <class>`, `corpus: ...`,
+      #     `behavior: ...`), or why it is invalid
+      Outcome = Struct.new(:site, :status, :by, keyword_init: true)
+
+      # Replays one mutant and says which check, if any, noticed.
+      #
+      # The trials run in order and stop at the first that fails. Each answers whether it killed the
+      # mutant and whether the mutant behaved differently from the original under it; a mutant that
+      # differed everywhere it was looked at and was never killed survived.
+      class Judge
+        TRIALS = %i[sequence_trial corpus_trial behavior_trial].freeze
+
+        # @param site [Site] what was changed
+        # @param copy [String] the mutated copy of the domain
+        # @param plan [Plan] what to replay
+        # @param baseline [Hash] what `Checks.baseline` answered for the unmutated domain
+        # @return [Outcome] the verdict
+        def self.call(site, copy, plan, baseline) = new(site, copy, plan, baseline).call
+
+        def initialize(site, copy, plan, baseline)
+          @site = site
+          @copy = copy
+          @plan = plan
+          @baseline = baseline
+        end
+
+        # @return [Outcome] invalid when it does not boot, killed by the first failing trial,
+        #   otherwise survived or unreached by whether anything differed
+        def call
+          reason = Checks.boot_failure(@copy)
+          return outcome(:invalid, reason) if reason
+
+          run_trials
+        rescue StandardError, ScriptError => e
+          outcome(:killed, "crash: #{e.class}")
+        end
+
+        private
+
+        def run_trials
+          differed = false
+          TRIALS.each do |trial|
+            killer, changed = send(trial)
+            return outcome(:killed, killer) if killer
+
+            differed ||= changed
+          end
+          outcome(differed ? :survived : :unreached)
+        end
+
+        def outcome(status, by = nil) = Outcome.new(site: @site, status: status, by: by)
+
+        def sequence_trial
+          differed = false
+          @plan.sequences.each_with_index do |steps, index|
+            history = Replay.call(@copy, steps)
+            broken = Checks.property_failure(history)
+            return [broken, true] if broken
+
+            differed ||= Observation.of(history) != @baseline[:sequences][index]
+          end
+          [nil, differed]
+        end
+
+        def corpus_trial
+          return [nil, false] unless @plan.corpus
+
+          report = Checks.corpus_report(@copy, @plan.corpus)
+          unmet = Checks.unmet_expectation(@plan.corpus, report)
+          return ["corpus: #{unmet}", true] if unmet
+
+          [nil, Observation.of(report) != @baseline[:corpus]]
+        end
+
+        def behavior_trial
+          failing = (Checks.failing_behaviors(@copy) - @baseline[:failing_behaviors]).first
+          [failing && "behavior: #{failing}", !failing.nil?]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+require "json"
+
+module Hecks
+  module Fuzzing
+    module Mutation
+      # A history or report reduced to plain values, so two runs compare equal when they did the
+      # same thing and differ when they did not.
+      module Observation
+        PARTS = %i[instances events refusals reactions sagas queries].freeze
+        PLAIN = [String, Numeric, true, false, nil].freeze
+
+        module_function
+
+        # @param history [Hash] a replay's history, or a `hecks run` report
+        # @return [String] canonical JSON of its observable parts
+        def of(history)
+          JSON.generate(plain(history.slice(*PARTS)))
+        end
+
+        # @return [Object] the value as hashes, arrays, strings, numbers and booleans only
+        def plain(value)
+          case value
+          when Hash then value.sort_by { |key, _| key.to_s }.to_h { |key, item| [key.to_s, plain(item)] }
+          when Array then value.map { |item| plain(item) }
+          when *PLAIN then value
+          else opaque(value)
+          end
+        end
+
+        # An object that is not plain data: its own hash form when it has one, else its text with
+        # the address that would differ between runs taken out.
+        def opaque(value)
+          value.respond_to?(:to_h) ? plain(value.to_h) : value.to_s.gsub(/0x\h+/, "0x")
+        end
+      end
+    end
+  end
+end