hecks 2.9.0 → 3.0.1

data/lib/hecks/fuzzing/nondeterministic.rb

@@ -0,0 +1,51 @@
+module Hecks
+  module Fuzzing
+    # Fields dropped before two histories are compared, declared once per shape they ride on.
+    # A literal except-list naming any of them under lib/hecks/fuzzing fails its spec.
+    module Nondeterministic
+      FIELDS = {
+        query_row:  {
+          instances_at: "a full state snapshot taken for the query oracle's own use " \
+                        "(Properties::Querying); the same state is already compared as `instances`, " \
+                        "so keeping it would re-report one instances divergence under every query step"
+        }.freeze,
+        outbox_row: {
+          event_uid:   "`Runtime::Outbox::Fanout#rows_for`'s own SecureRandom.uuid, minted fresh per " \
+                       "enqueue and kept off `Event#to_h` — relay bookkeeping, never something the " \
+                       "domain produced, so two otherwise-identical replays carry two different uuids",
+          delivery_id: "`\"\#{event_uid}/\#{consumer}\"` — inherits event_uid's per-enqueue uuid"
+        }.freeze,
+        event:      {
+          occurred_at: "a wall-clock read; never reproducible byte-for-byte between two independent " \
+                       "runs (Replay's own projected `:events` leave it off for the same reason)"
+        }.freeze,
+        history:    {
+          bluebook:  "a live IR object (the first-loaded bluebook) handed to properties — an object " \
+                     "identity, not a value, so two boots never compare equal on it",
+          bluebooks: "the full live IR map, keyed by domain — object identities, same as `bluebook`"
+        }.freeze
+      }.freeze
+
+      module_function
+
+      # The field names declared for one comparison group.
+      #
+      # @raise [KeyError] if `group` names no declared group
+      def names(group)
+        FIELDS.fetch(group).keys
+      end
+
+      # Every declared name, across every group.
+      def all_names
+        FIELDS.values.flat_map(&:keys).uniq
+      end
+
+      # `hash` without `group`'s fields; expects symbol keys.
+      #
+      # @raise [KeyError] if `group` names no declared group
+      def strip(hash, group)
+        hash.except(*names(group))
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/outside_world.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../runtime/errors"
+
+module Hecks
+  module Fuzzing
+    # What a replay asks in place of a port's adapter: an object that refuses every question.
+    #
+    # A domain's adapters reach outside the process, and the chapters of this repository that
+    # drive tools (the shell, git, child processes, the file system) would run them for real from
+    # a generated sequence. A replay checks the domain's own rules, so the adapter never runs:
+    # the operation is refused, which a port operation records as its `refuses` event and a query
+    # answered by a port raises like any domain refusal.
+    #
+    # The refusal is a `GivenNotMet` for the runtime's sake but not one a `given` declares, and no
+    # property that reads guard descriptions quotes it.
+    class OutsideWorld
+      # The refusal every question to a stand-in ends in.
+      class Refused < Runtime::GivenNotMet; end
+
+      # @param port_name [String] the port whose adapter this stands in for
+      # @param asked [String] what was being asked, worded into the refusal
+      # @return [OutsideWorld] the stand-in
+      def self.call(port_name, asked)
+        new(port_name, asked)
+      end
+
+      # @param port_name [String] the port whose adapter this stands in for
+      # @param asked [String] what was being asked, worded into the refusal
+      def initialize(port_name, asked)
+        @port_name = port_name
+        @asked = asked
+      end
+
+      # Every method a port could declare exists here, and refuses.
+      def respond_to_missing?(_name, _include_private = false) = true
+
+      # @raise [Refused] always
+      def method_missing(name, *, **)
+        raise Refused, "#{@asked} was not asked of the #{@port_name} port's adapter: a replay runs " \
+                       "no adapter (#{name})"
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/persistence_parity.rb

@@ -0,0 +1,102 @@
+require "json"
+require_relative "replay"
+require_relative "nondeterministic"
+
+module Hecks
+  module Fuzzing
+    # Differential check of one Ruby engine against two persistences, `left:` and `right:`.
+    # Defaults to Memory vs a disposable `PostgresEra` database, which needs `database:`/`schema:`.
+    module PersistenceParity
+      module_function
+
+      # Replays `steps` on both adapters and lists where the results differ.
+      #
+      # Compares the same six fields as `hecks quality_control ask run`'s Ruby-vs-Rust mode. Both
+      # results are JSON-round-tripped so plain data compares equal on both sides.
+      #
+      # @param left [Symbol] an `IsolatedBoot` adapter: `:memory`, `:sqlite`, `:postgres`,
+      #   `:postgres_era`
+      # @param right [Symbol] the second adapter, same set as `left`
+      # @param database [String, nil] required when either side is `:postgres_era`
+      # @param schema [String, nil] required when either side is `:postgres_era`
+      # @return [Array<Hash>] entries `{field: String, left => Object, right => Object}`,
+      #   keyed by the adapter symbols; empty if both sides agree
+      def diff(domain_path, steps, left: :memory, right: :postgres_era, database: nil, schema: nil)
+        left_result  = Replay.call(domain_path, steps, adapter: left, database: database, schema: schema)
+        right_result = Replay.call(domain_path, steps, adapter: right, database: database, schema: schema)
+
+        divergences = []
+        divergences.concat(diff_instances(left_result, right_result, left, right))
+        divergences.concat(diff_events(left_result, right_result, left, right))
+        divergences.concat(diff_refusals(left_result, right_result, left, right))
+        divergences.concat(diff_queries(left_result, right_result, left, right))
+        divergences.concat(diff_sagas(left_result, right_result, left, right))
+        divergences.concat(diff_reactions(left_result, right_result, left, right))
+        divergences
+      end
+
+      # Round-trips `value` through JSON so both sides compare as plain data.
+      def as_json(value) = JSON.parse(JSON.generate(value))
+
+      # Compares both sides' stored instances.
+      def diff_instances(left_result, right_result, left, right)
+        l = as_json(left_result[:instances])
+        r = as_json(right_result[:instances])
+        return [] if l == r
+
+        [{ field: "instances", left => l, right => r }]
+      end
+
+      # Compares both sides' emitted events.
+      def diff_events(left_result, right_result, left, right)
+        l = as_json(left_result[:events])
+        r = as_json(right_result[:events])
+        return [] if l == r
+
+        [{ field: "events", left => l, right => r }]
+      end
+
+      # Compares both sides' refusals, with `verb`/`kind` as strings.
+      def diff_refusals(left_result, right_result, left, right)
+        normalize = lambda do |refusals|
+          refusals.map { |r| { "verb" => r[:verb].to_s, "kind" => r[:kind].to_s, "error" => r[:error] } }
+        end
+        l = normalize.call(left_result[:refusals])
+        r = normalize.call(right_result[:refusals])
+        return [] if l == r
+
+        [{ field: "refusals", left => l, right => r }]
+      end
+
+      # Compares both sides' query answers, minus the `query_row` fields.
+      #
+      # The `Nondeterministic` `query_row` group is dropped; instances are already compared.
+      def diff_queries(left_result, right_result, left, right)
+        strip = ->(rows) { rows.map { |row| Nondeterministic.strip(row, :query_row) } }
+        l = as_json(strip.call(left_result[:queries]))
+        r = as_json(strip.call(right_result[:queries]))
+        return [] if l == r
+
+        [{ field: "queries", left => l, right => r }]
+      end
+
+      # Compares both sides' saga logs.
+      def diff_sagas(left_result, right_result, left, right)
+        l = as_json(left_result[:sagas])
+        r = as_json(right_result[:sagas])
+        return [] if l == r
+
+        [{ field: "sagas", left => l, right => r }]
+      end
+
+      # Compares both sides' reaction logs.
+      def diff_reactions(left_result, right_result, left, right)
+        l = as_json(left_result[:reactions])
+        r = as_json(right_result[:reactions])
+        return [] if l == r
+
+        [{ field: "reactions", left => l, right => r }]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Property: every `corrects` mutation points at an earlier event in the same history.
+      module Corrections
+        # Every event emitted by a command with a `corrects` mutation, aggregate-level or
+        # nested in entities, needs an earlier event with the corrected name and same id.
+        #
+        # `history[:events]` is in occurrence order, so "earlier" is array position.
+        # Entity-level `corrects` is checked by neither dispatch nor build, so only this
+        # property catches it going wrong.
+        #
+        # @param history [Hash] a replayed history as returned by `Replay.call`
+        # @return [true, String] true if every event emitted by a `corrects`-bearing
+        #   command has a matching, strictly earlier corrected event in the same
+        #   history; otherwise a message listing every unmatched correction
+        def corrections_reference_an_emitted_event(history)
+          violations = []
+
+          (history[:bluebooks] || {}).each do |domain, bluebook|
+            bluebook.aggregates.each do |aggregate|
+              aggregate_key = "#{domain}::#{aggregate.hecks_name}"
+
+              each_command_including_entities(aggregate) do |command|
+                corrects_mutations = command.mutations.select { |mutation| mutation.op == :corrects }
+                next if corrects_mutations.empty?
+
+                corrects_mutations.each do |mutation|
+                  corrected_event = mutation.target.to_s
+
+                  command.emits.each do |produced_event_name|
+                    violations.concat(unmatched_corrections(history[:events], aggregate_key,
+                                                            produced_event_name.to_s, corrected_event,
+                                                            command.hecks_name))
+                  end
+                end
+              end
+            end
+          end
+
+          violations.empty? || violations.uniq.join("; ")
+        end
+
+        # Finds every occurrence of `produced_event_name`, on `aggregate_key`, with no
+        # matching `corrected_event` for the same id appearing earlier in `events`.
+        #
+        # @param events [Array<Hash>] `history[:events]`, in occurrence order
+        # @param aggregate_key [String] `"domain::AggregateName"` the events belong to
+        # @param produced_event_name [String] name of the event a `corrects` mutation's
+        #   command emits
+        # @param corrected_event [String] name of the event the mutation claims to correct
+        # @param command_name [String] the command's own `hecks_name`, for the message
+        # @return [Array<String>] one message per occurrence with no matching earlier
+        #   corrected event; empty when every occurrence is matched
+        def unmatched_corrections(events, aggregate_key, produced_event_name, corrected_event, command_name)
+          own_events = events.each_with_index.select do |event, _index|
+            event[:name] == produced_event_name && event[:aggregate] == aggregate_key
+          end
+
+          own_events.filter_map do |event, index|
+            preceding = events.first(index)
+            next if preceding.any? do |earlier|
+              earlier[:name] == corrected_event && earlier[:aggregate] == aggregate_key &&
+              earlier[:id].to_s == event[:id].to_s
+            end
+
+            "#{command_name} (#{aggregate_key}##{event[:id]}) emitted #{produced_event_name}, claiming to " \
+              "correct #{corrected_event}, but no #{corrected_event} for the same aggregate/id appears " \
+              "earlier in this history"
+          end
+        end
+
+        # Yields every command on `owner` and, recursively, on its entities (ADR 0026).
+        #
+        # @param owner [Bluebook::Aggregate, Bluebook::Entity] the aggregate or entity
+        #   whose own commands, and whose entities' commands, to walk
+        # @yield [command] once per declared command, aggregate-level or nested
+        # @yieldparam command [Bluebook::Command] a command declared on `owner` or one
+        #   of its entities
+        # @return [void]
+        def each_command_including_entities(owner, &block)
+          owner.commands.each(&block)
+          owner.entities.each { |entity| each_command_including_entities(entity, &block) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,314 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Property: a dry-run step leaves the event count and every instance unchanged.
+      # Entries without before/after snapshots (hand-built histories) are skipped.
+      module DryRuns
+        # Checks that every dry-run step left neither the event count nor any
+        # instance's state changed.
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true if every dry-run trace shows no change; otherwise
+        #   a semicolon-joined message naming each offending dry run
+        def dry_runs_leave_no_trace(history)
+          offenders = Array(history[:dry_run_traces]).filter_map do |entry|
+            before = entry[:before]
+            after  = entry[:after]
+            next unless before && after
+
+            traces = []
+            traces << "events #{before[:events]} -> #{after[:events]}" unless before[:events] == after[:events]
+            traces << "instances changed" unless before[:instances] == after[:instances]
+            next if traces.empty?
+
+            "dry run of #{entry[:verb]} (ok: #{entry[:ok]}) left a trace: #{traces.join(', ')}"
+          end
+
+          offenders.empty? || offenders.join("; ")
+        end
+      end
+
+      # Properties: saga/policy dispatch args match their `with_spec`, and command
+      # mutations match an independent recomputation.
+      module DispatchAndMutations
+        # Checks saga and policy dispatch args against an independent re-derivation of
+        # `with_spec`. Re-deriving, not calling the interpreter again, keeps the check
+        # from agreeing with itself. Args are compared as captured live, because a
+        # saga's memory keeps changing across a run.
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true if every saga and policy dispatch's own bound args
+        #   match an independent re-derivation of their `with_spec`; otherwise a
+        #   semicolon-joined message naming each offending dispatch
+        def dispatch_binding_fidelity(history)
+          saga_offenders = history.fetch(:saga_dispatches, []).filter_map do |entry|
+            expected = resolve_dispatch_binding(entry)
+            next if expected == entry[:args]
+
+            "#{entry[:process_manager]}##{entry[:instance]} dispatching #{entry[:dispatch]} on #{entry[:on]} — " \
+              "bound #{entry[:args].inspect}, but independently re-deriving with_spec's own resolution gives " \
+              "#{expected.inspect}"
+          end
+
+          policy_offenders = history.fetch(:policy_dispatches, []).filter_map do |entry|
+            expected = resolve_trigger_binding(entry)
+            next if expected == entry[:args]
+
+            "#{entry[:policy]} on #{entry[:on]} — bound #{entry[:args].inspect}, but independently re-deriving " \
+              "with_spec's own resolution gives #{expected.inspect}"
+          end
+
+          offenders = saga_offenders + policy_offenders
+          offenders.empty? || offenders.join("; ")
+        end
+
+        # Re-derives SagaInterpreter#dispatch_args: a literal, the correlation key,
+        # the triggering event's payload, or else the saga's carried memory.
+        def resolve_dispatch_binding(entry)
+          entry[:with_spec].to_h do |key, value|
+            resolved = if !value.is_a?(Symbol) then value
+                       elsif value == entry[:correlation_head] then entry[:instance]
+                       elsif entry[:event_payload].key?(value) then entry[:event_payload][value]
+                       else entry[:memory][value]
+                       end
+            [key.to_sym, Runtime::Value.materialize(resolved)]
+          end
+        end
+
+        # Re-derives PolicyInterpreter#trigger_args: a policy has no correlation or
+        # memory, so the trigger payload is the only source.
+        def resolve_trigger_binding(entry)
+          entry[:with_spec].to_h do |key, value|
+            resolved = value.is_a?(Symbol) ? entry[:payload][value] : value
+            [key.to_sym, Runtime::Value.materialize(resolved)]
+          end
+        end
+
+        # Ops with an independent recomputation here. `:increment` and `:decrement` are
+        # left out: their value-object and overflow handling is a much larger reproduction.
+        #
+        # Only the entity-scoped applier (`EntityElement#apply_to_element`) is
+        # reproduced, since replay captures mutation traces for entity-owned commands only.
+        # `:set` needs its own recomputation because the self-consistency checks share the
+        # same `step_apply_mutations` call and cannot see a wrong `:set` result.
+        #
+        # `:unrecomputable` (never a finding) marks a step whose fuzzer-malformed args do
+        # not fit the op's contract.
+        RECOMPUTABLE_MUTATION_OPS = %i[append remove multiply clamp set].freeze
+
+        # Checks that every recomputable mutation an entity-owned command
+        # applied landed on the same after-state an independent
+        # recomputation of the same rule produces.
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true if every recomputable mutation's after-state
+        #   matches an independent recomputation; otherwise a semicolon-joined message
+        #   naming each offending mutation
+        def mutations_match_recompute(history)
+          bluebooks = history.fetch(:bluebooks)
+
+          offenders = history.fetch(:mutation_traces, []).flat_map do |entry|
+            next [] unless entry[:after]
+
+            command = command_for_verb(bluebooks, entry[:verb])
+            next [] unless command
+
+            aggregate = aggregate_for_verb(bluebooks, entry[:verb])
+            next [] unless aggregate
+
+            owner = owner_for_verb(bluebooks, entry[:verb]) || aggregate
+
+            command.mutations.select { |m| RECOMPUTABLE_MUTATION_OPS.include?(m.op) }.filter_map do |mutation|
+              expected = recompute_mutation(mutation, entry[:before][mutation.target], entry[:args], entry[:before],
+                                            aggregate, command, owner)
+              next if expected == :unrecomputable
+
+              actual = entry[:after][mutation.target]
+              next if symbolize_deep(expected) == symbolize_deep(actual)
+
+              "#{entry[:verb]} — #{mutation.op} on #{mutation.target} — recomputing independently gives " \
+                "#{expected.inspect}, but the real dispatch left #{actual.inspect}"
+            end
+          end
+
+          offenders.empty? || offenders.join("; ")
+        end
+
+        # Root aggregate for `verb`, derived from the verb alone because hand-built
+        # entries may lack `:domain`/`:aggregate`. Value-object types resolve against
+        # the root's namespace only.
+        def aggregate_for_verb(bluebooks, verb)
+          domain_name, aggregate_name, = Naming.split_verb(verb)
+          return nil unless domain_name
+
+          bluebooks[domain_name]&.aggregate(aggregate_name)
+        end
+
+        # The construct declaring `mutation.target`: the root aggregate, or the owning
+        # entity for a dot-shaped command. Attribute lookups must ask that construct,
+        # as `EntityElement#locate_chain` does.
+        def owner_for_verb(bluebooks, verb)
+          domain_name, aggregate_name, command_path = Naming.split_verb(verb)
+          return nil unless command_path
+
+          aggregate = bluebooks[domain_name]&.aggregate(aggregate_name)
+          return nil unless aggregate
+          return aggregate unless command_path.include?(".")
+
+          entity_name, = command_path.split(".", 2)
+          aggregate.entities.find { |candidate| candidate.hecks_name == entity_name }
+        end
+
+        # Dispatches to the recompute rule for `mutation.op`.
+        def recompute_mutation(mutation, current, args, before_scope, aggregate, command, owner = aggregate)
+          case mutation.op
+          when :append
+            recompute_append(current, mutation.source, before_scope, args, aggregate, command, owner, mutation.target)
+          when :remove   then recompute_remove(current, mutation.source, args)
+          when :multiply then recompute_multiply(current, resolve_mutation_source(mutation.source, args))
+          when :clamp    then recompute_clamp(current, mutation.source)
+          when :set      then recompute_set(mutation.source, args, aggregate, owner, mutation.target)
+          end
+        end
+
+        # Re-derives the `:set` branch of `EntityElement#apply_to_element`. The
+        # attribute comes from `owner`, not the root aggregate, which would leave a
+        # nested entity's value uncoerced and disagree with the real after-state.
+        # Any raise means the raw material was wrong, so the result is `:unrecomputable`.
+        def recompute_set(source, args, aggregate, owner, target)
+          raw = resolve_mutation_source(source, args)
+          attribute = owner&.attribute(target)
+          coerced = attribute ? Runtime::Value.for_attribute(aggregate, attribute, raw) : raw
+          Runtime::Value.materialize(coerced)
+        rescue StandardError
+          :unrecomputable
+        end
+
+        # Re-derives `EntityElement#appended_to_element`: each field resolves from a
+        # caller arg (coerced as `Interpreting#coerce_declared_arguments` does) or from
+        # the entity's current field (already materialized), then the element is appended.
+        # A nested-entity element also gets its declared defaults.
+        def recompute_append(current, source_map, before_scope, args, aggregate, command, owner = aggregate, target = nil)
+          fields = source_map.transform_values do |source|
+            resolve_mutation_append_field(source, before_scope, args, aggregate, command)
+          end
+          fill_recompute_declared_defaults(aggregate, owner, target, fields)
+          Array(current) + [symbolize_deep(fields)]
+        end
+
+        # Fills defaults for a nested-entity element via `Instance.default_for`, which is
+        # independently tested. No-op unless `target` names an entity under `owner`
+        # (`owner.entities`, not `aggregate.entities`).
+        #
+        # A value-object element type (the more common shape: `list_of` a plain composite,
+        # not a nested entity) defaults the other way real dispatch does — through
+        # `Runtime::Value.apply_defaults`, the exact primitive `EntityElement#appended_to_
+        # element`'s own `Value.build` call uses. Without this branch, a caller-omitted,
+        # VO-declared `default:` field is left out of the recomputed element entirely,
+        # disagreeing with real dispatch's fully-defaulted one.
+        def fill_recompute_declared_defaults(aggregate, owner, target, fields)
+          return fields unless target
+
+          element_type = owner&.attribute(target)&.type
+          return fields unless element_type
+
+          entity = owner.entities.find { |piece| piece.hecks_name == element_type.to_s }
+          if entity
+            entity.attributes.each do |attribute|
+              next if fields.key?(attribute.name)
+
+              fields[attribute.name] = attribute.list? ? [] : Runtime::Instance.default_for(aggregate, attribute)
+            end
+            return fields
+          end
+
+          value_object = aggregate.value_object(element_type)
+          return fields unless value_object
+
+          Runtime::Value.apply_defaults(value_object, fields)
+        end
+
+        # Resolves one appended field's value from its declared source.
+        def resolve_mutation_append_field(source, before_scope, args, aggregate, command)
+          return source unless source.is_a?(Symbol)
+          return before_scope[source] unless args.key?(source)
+
+          coerce_recompute_append_arg(aggregate, command, source, args[source])
+        end
+
+        # Coerces a raw arg only when `source` is a declared attribute of the command,
+        # as a real dispatch does. Materialized so the comparison is plain data on both sides.
+        def coerce_recompute_append_arg(aggregate, command, source, raw)
+          attribute = command.attribute(source)
+          return raw unless attribute
+
+          Runtime::Value.materialize(Runtime::Value.for_attribute(aggregate, attribute, raw, argument: true))
+        end
+
+        # Re-derives `MutationApplier#removed`: removes every value-equal element.
+        # `Value.materialize` first: once `args` arrives normalized (replay.rb's
+        # `build_mutation_trace`), a composite `remove:` source is already a built
+        # `Runtime::Value` with its own declared defaults filled — comparing it
+        # unmaterialized against `current`'s plain Hashes would never match, wrongly
+        # keeping an element real dispatch correctly removed.
+        def recompute_remove(current, source, args)
+          target = symbolize_deep(Runtime::Value.materialize(resolve_mutation_source(source, args)))
+          Array(current).reject { |element| symbolize_deep(element) == target }
+        end
+
+        # Re-derives `CommandRules::Arithmetic#multiply` on plain data: a Hash with one
+        # numeric field scales that field, a bare Numeric scales itself. A nil
+        # `current` is treated as 0.
+        def recompute_multiply(current, amount)
+          return :unrecomputable unless amount.is_a?(Numeric)
+
+          current ||= 0
+          if current.is_a?(Hash)
+            field = current.keys.find { |f| current[f].is_a?(Numeric) }
+            return :unrecomputable unless field
+
+            current.merge(field => current[field] * amount)
+          elsif current.is_a?(Numeric)
+            current * amount
+          else
+            :unrecomputable
+          end
+        end
+
+        # Re-derives `CommandRules::Arithmetic#clamp` like #recompute_multiply. The
+        # source is always a literal `[min, max]`, never an argument reference.
+        def recompute_clamp(current, bounds)
+          return :unrecomputable unless bounds.is_a?(Array) && bounds.size == 2
+
+          min, max = bounds
+          current ||= 0
+          if current.is_a?(Hash)
+            field = current.keys.find { |f| current[f].is_a?(Numeric) }
+            return :unrecomputable unless field
+
+            current.merge(field => current[field].clamp(min, max))
+          elsif current.is_a?(Numeric)
+            current.clamp(min, max)
+          else
+            :unrecomputable
+          end
+        end
+
+        # A mutation source is an argument name (Symbol) or a literal.
+        def resolve_mutation_source(source, args)
+          source.is_a?(Symbol) ? args[source] : source
+        end
+
+        # Symbolizes hash keys recursively. Generated args carry string keys while
+        # materialized trace state carries symbols, and `Hash#==` would otherwise differ.
+        def symbolize_deep(value)
+          case value
+          when Hash  then value.to_h { |key, val| [key.to_sym, symbolize_deep(val)] }
+          when Array then value.map { |val| symbolize_deep(val) }
+          else value
+          end
+        end
+      end
+    end
+  end
+end