hecks 3.5.0 → 3.6.0

data/lib/hecks/fuzzing/self_consistency/sagas.rb

@@ -0,0 +1,93 @@
+require "tmpdir"
+require_relative "../../runtime/saga_interpreter"
+
+module Hecks
+  module Fuzzing
+    module SelfConsistency
+      # The saga rehydration check: checkpoints written through Heki and read back cold.
+      # Mixed into `SelfConsistency`, whose `guarded_heki` it uses.
+      module Sagas
+        # A saga checkpoint written through Heki and read back cold must equal the live saga
+        # instances. One finding per (domain, process manager).
+        #
+        # `completed_compensations` is not compared; `history[:saga_instances]` never records it.
+        def check_saga_rehydration(runtime, history)
+          saga_groups(runtime, history).filter_map do |domain_name, process_manager, anchor, persisted|
+            saga_rehydration_finding(anchor, domain_name, process_manager, persisted)
+          end
+        end
+
+        # Every `[domain, process manager, anchor aggregate, persisted conversations]` with at
+        # least one live conversation.
+        def saga_groups(runtime, history)
+          saga_instances = history[:saga_instances] || {}
+          each_domain_process_manager(runtime).filter_map do |domain_name, process_manager|
+            persisted = saga_instances[process_manager.name]
+            next if persisted.nil? || persisted.empty?
+
+            anchor = runtime.registry.bluebook(domain_name).aggregates.first
+            [domain_name, process_manager, anchor, persisted] if anchor
+          end
+        end
+
+        # The finding for one process manager whose cold-read checkpoints differ from live, or nil.
+        def saga_rehydration_finding(anchor, domain_name, process_manager, persisted)
+          Dir.mktmpdir("hecks-self-consistency-saga") do |tmp|
+            write_saga_checkpoints(anchor, tmp, domain_name, process_manager, persisted)
+            live       = normalize_saga_rows(persisted)
+            rehydrated = cold_read_saga_rows(anchor, tmp, domain_name)
+            next if rehydrated == live
+
+            { field: "saga_rehydration", domain: domain_name, process_manager: process_manager.name,
+              live: live, rehydrated: rehydrated }
+          end
+        end
+
+        # Writes every live conversation of `process_manager` through Heki under `tmp`.
+        def write_saga_checkpoints(anchor, tmp, domain_name, process_manager, persisted)
+          writer = guarded_heki(aggregate: anchor, root: tmp, settings: { domain: domain_name })
+          persisted.each do |correlation, saga|
+            writer.save_saga(process_manager: process_manager.name, correlation: correlation.to_s,
+                             state: saga[:state], memory: saga[:memory], completed_compensations: [])
+          end
+        end
+
+        # Every [domain, process manager] pair any loaded bluebook declares.
+        def each_domain_process_manager(runtime)
+          found = []
+          runtime.registry.bluebooks.each do |domain_name, bluebook|
+            bluebook.process_managers.each { |pm| found << [domain_name, pm] }
+          end
+          found
+        end
+
+        # Live saga rows with `memory` deep-stringified, matching what a Heki round trip yields.
+        def normalize_saga_rows(persisted)
+          persisted.each_with_object({}) do |(correlation, saga), rows|
+            rows[correlation.to_s] = { state: saga[:state], memory: deep_stringify_keys(saga[:memory]) }
+          end
+        end
+
+        # A fresh `Heki` reader at the same path: a new instance has no memoized store, so the
+        # read goes through the on-disk snapshot and journal rather than the writer's memory.
+        def cold_read_saga_rows(anchor, tmp, domain_name)
+          reader = guarded_heki(aggregate: anchor, root: tmp, settings: { domain: domain_name })
+          reader.each_saga.with_object({}) do |(_pm, correlation, state, memory, _completed), rows|
+            rows[correlation] = { state: state, memory: deep_stringify_keys(memory) }
+          end
+        end
+
+        # `SagaStore#each_saga` symbolizes only top-level `memory` keys, while the live side is
+        # symbol-keyed throughout. Stringifying both sides tells that accepted difference apart
+        # from real data loss.
+        def deep_stringify_keys(value)
+          case value
+          when Hash  then value.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify_keys(v) }
+          when Array then value.map { |item| deep_stringify_keys(item) }
+          else value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/self_consistency/value_objects.rb

@@ -0,0 +1,87 @@
+require "json"
+
+module Hecks
+  module Fuzzing
+    module SelfConsistency
+      # The value-object round trip: every value object a sequence built must survive
+      # `to_json` then `Value.build`. Mixed into `SelfConsistency`.
+      module ValueObjects
+        # Every value object the sequence built must survive `to_json` then `Value.build`.
+        #
+        # The owning aggregate is passed to `build` so nested composite fields resolve; with `nil`
+        # they come back as bare Hashes, a false positive. Query rows are skipped because they
+        # name no single owning aggregate.
+        def check_value_object_round_trip(history)
+          value_objects_in(history).filter_map { |value, aggregate| round_trip_finding(value, aggregate) }
+        end
+
+        # Every `[value, owning aggregate]` pair found in the history's instances and events.
+        def value_objects_in(history)
+          bluebooks = history[:bluebooks] || {}
+          seen = {}.compare_by_identity
+          found = []
+
+          history[:instances].each do |key, state|
+            walk_value_objects(state, found, seen, instance_owner(bluebooks, key))
+          end
+
+          history[:events].each do |event|
+            walk_value_objects(event[:payload], found, seen, owning_aggregate(bluebooks, event[:aggregate].to_s))
+          end
+
+          found
+        end
+
+        # The aggregate a stored-record key `Domain::Aggregate#id` belongs to, or nil.
+        def instance_owner(bluebooks, key) = owning_aggregate(bluebooks, key.to_s.split("#", 2).first.to_s)
+
+        # The aggregate a `"Domain::Aggregate"` name refers to, or nil.
+        def owning_aggregate(bluebooks, qualified_name)
+          domain_name, aggregate_name = qualified_name.split("::", 2)
+          bluebooks[domain_name]&.aggregate(aggregate_name)
+        end
+
+        # The finding for one value that does not survive its round trip, or nil.
+        def round_trip_finding(value, aggregate)
+          rebuilt, error = rebuild(value, aggregate)
+          if error
+            return { field: "value_object_round_trip", type: value.type_name, original: value.to_h,
+                     error: "#{error.class}: #{error.message}" }
+          end
+          return if rebuilt == value
+
+          { field: "value_object_round_trip", type: value.type_name, original: value.to_h,
+            rehydrated: rebuilt.to_h }
+        end
+
+        # `[rebuilt value, nil]`, or `[nil, the error]` when the rebuild raises.
+        def rebuild(value, aggregate)
+          [Runtime::Value.build(value.value_object, JSON.parse(value.to_json), aggregate), nil]
+        rescue StandardError => e
+          [nil, e]
+        end
+
+        # Recurses via `#[]` rather than `#to_h`, which would materialize nested values away.
+        # `seen` compares by identity: a live state and an event payload can share one object,
+        # while two equal but distinct value objects are still two round trips to prove.
+        def walk_value_objects(node, found, seen, aggregate)
+          case node
+          when Runtime::Value then walk_value_object(node, found, seen, aggregate)
+          when Hash           then node.each_value { |value| walk_value_objects(value, found, seen, aggregate) }
+          when Array          then node.each { |value| walk_value_objects(value, found, seen, aggregate) }
+          end
+        end
+
+        def walk_value_object(node, found, seen, aggregate)
+          return if seen[node]
+
+          seen[node] = true
+          found << [node, aggregate]
+          node.value_object.attributes.each do |attribute|
+            walk_value_objects(node[attribute.name], found, seen, aggregate)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/self_consistency.rb

@@ -3,12 +3,19 @@ require "tmpdir"
 require "open3"
 require_relative "../adapters/driven/heki"
 require_relative "../runtime/saga_interpreter"
+require_relative "self_consistency/saga_redelivery"
+require_relative "self_consistency/sagas"
+require_relative "self_consistency/value_objects"
 
 module Hecks
   module Fuzzing
     # Checks that one engine agrees with itself: journal rehydration, replay idempotency and
     # value-object round trips, for Ruby and for the compiled Rust binary.
     module SelfConsistency
+      extend SagaRedelivery
+      extend Sagas
+      extend ValueObjects
+
       module_function
 
       # Guarded like a runtime repository: these adapters bypass `RepositoryFactory.build`,
@@ -42,7 +49,7 @@ module Hecks
 
       # Folding the same entries into the same store twice must change nothing.
       def check_idempotency(runtime)
-        each_touched_repository(runtime).filter_map do |domain_name, aggregate, repository, entries|
+        each_touched_repository(runtime).filter_map do |domain_name, aggregate, _repository, entries|
           Dir.mktmpdir("hecks-self-consistency") do |tmp|
             writer = guarded_heki(aggregate: aggregate, root: tmp)
             once   = fold!(writer, tmp, aggregate, entries)
@@ -55,99 +62,6 @@ module Hecks
         end
       end
 
-      # Every value object the sequence built must survive `to_json` then `Value.build`.
-      #
-      # The owning aggregate is passed to `build` so nested composite fields resolve; with `nil`
-      # they come back as bare Hashes, a false positive. Query rows are skipped because they
-      # name no single owning aggregate.
-      def check_value_object_round_trip(history)
-        bluebooks = history[:bluebooks] || {}
-        seen = {}.compare_by_identity
-        found = []
-
-        history[:instances].each do |key, state|
-          domain_name, aggregate_name = key.to_s.split("#", 2).first.to_s.split("::", 2)
-          aggregate = bluebooks[domain_name]&.aggregate(aggregate_name)
-          walk_value_objects(state, found, seen, aggregate)
-        end
-
-        history[:events].each do |event|
-          domain_name, aggregate_name = event[:aggregate].to_s.split("::", 2)
-          aggregate = bluebooks[domain_name]&.aggregate(aggregate_name)
-          walk_value_objects(event[:payload], found, seen, aggregate)
-        end
-
-        found.filter_map do |value, aggregate|
-          begin
-            rebuilt = Runtime::Value.build(value.value_object, JSON.parse(value.to_json), aggregate)
-          rescue StandardError => e
-            next { field: "value_object_round_trip", type: value.type_name, original: value.to_h,
-                   error: "#{e.class}: #{e.message}" }
-          end
-
-          next if rebuilt == value
-
-          { field: "value_object_round_trip", type: value.type_name, original: value.to_h,
-            rehydrated: rebuilt.to_h }
-        end
-      end
-
-      # A saga checkpoint written through Heki and read back cold must equal the live saga
-      # instances. One finding per (domain, process manager).
-      #
-      # `completed_compensations` is not compared; `history[:saga_instances]` never records it.
-      def check_saga_rehydration(runtime, history)
-        saga_instances = history[:saga_instances] || {}
-        each_domain_process_manager(runtime).filter_map do |domain_name, process_manager|
-          persisted = saga_instances[process_manager.name]
-          next if persisted.nil? || persisted.empty?
-
-          anchor = runtime.registry.bluebook(domain_name).aggregates.first
-          next unless anchor
-
-          Dir.mktmpdir("hecks-self-consistency-saga") do |tmp|
-            writer = guarded_heki(aggregate: anchor, root: tmp, settings: { domain: domain_name })
-            persisted.each do |correlation, saga|
-              writer.save_saga(process_manager: process_manager.name, correlation: correlation.to_s,
-                               state: saga[:state], memory: saga[:memory], completed_compensations: [])
-            end
-
-            live       = normalize_saga_rows(persisted)
-            rehydrated = cold_read_saga_rows(anchor, tmp, domain_name)
-            next if rehydrated == live
-
-            { field: "saga_rehydration", domain: domain_name, process_manager: process_manager.name,
-              live: live, rehydrated: rehydrated }
-          end
-        end
-      end
-
-      # A rehydrated saga checkpoint must not advance when its last event is redelivered.
-      #
-      # The live registry slot is swapped for the cold-read checkpoint and restored in `ensure`;
-      # safe because nothing reads the live registry after this runs. Only state/memory are
-      # compared: a leg whose `from:` and `to:` match legitimately re-runs.
-      def check_saga_idempotency(runtime, history)
-        saga_instances = history[:saga_instances] || {}
-        interpreter    = Runtime::SagaInterpreter.new(runtime.registry, door: runtime)
-
-        each_domain_process_manager(runtime).flat_map do |domain_name, process_manager|
-          persisted = saga_instances[process_manager.name]
-          next [] if persisted.nil? || persisted.empty?
-
-          anchor = runtime.registry.bluebook(domain_name).aggregates.first
-          next [] unless anchor
-
-          persisted.filter_map do |correlation, saga|
-            redelivery = last_advancing_event(runtime, interpreter, process_manager, correlation)
-            next unless redelivery
-
-            check_one_saga_redelivery(runtime, interpreter, domain_name, process_manager, anchor,
-                                      correlation, saga, redelivery)
-          end
-        end
-      end
-
       # Seeds a fresh invocation of the binary with prior "instances" and no steps.
       # `emitted_*` fields are not stripped: no Ruby side exists to disagree with, and stripping
       # only the result would report a false divergence on every record carrying one.
@@ -199,105 +113,6 @@ module Hecks
         repository.all.to_h { |record| [record.id.to_s, Runtime::Value.materialize(record.state)] }
       end
 
-      # Every [domain, process manager] pair any loaded bluebook declares.
-      def each_domain_process_manager(runtime)
-        found = []
-        runtime.registry.bluebooks.each do |domain_name, bluebook|
-          bluebook.process_managers.each { |pm| found << [domain_name, pm] }
-        end
-        found
-      end
-
-      # Live saga rows with `memory` deep-stringified, matching what a Heki round trip yields.
-      def normalize_saga_rows(persisted)
-        persisted.each_with_object({}) do |(correlation, saga), rows|
-          rows[correlation.to_s] = { state: saga[:state], memory: deep_stringify_keys(saga[:memory]) }
-        end
-      end
-
-      # A fresh `Heki` reader at the same path: a new instance has no memoized store, so the
-      # read goes through the on-disk snapshot and journal rather than the writer's memory.
-      def cold_read_saga_rows(anchor, tmp, domain_name)
-        reader = guarded_heki(aggregate: anchor, root: tmp, settings: { domain: domain_name })
-        reader.each_saga.with_object({}) do |(_pm, correlation, state, memory, _completed), rows|
-          rows[correlation] = { state: state, memory: deep_stringify_keys(memory) }
-        end
-      end
-
-      # `SagaStore#each_saga` symbolizes only top-level `memory` keys, while the live side is
-      # symbol-keyed throughout. Stringifying both sides tells that accepted difference apart
-      # from real data loss.
-      def deep_stringify_keys(value)
-        case value
-        when Hash  then value.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify_keys(v) }
-        when Array then value.map { |item| deep_stringify_keys(item) }
-        else value
-        end
-      end
-
-      # The domain event the correlation's current checkpoint last advanced on, or nil if it
-      # never advanced. Skips the synthetic `REFUSED` trigger, which has no event to redeliver.
-      #
-      # Uses `send(:saga_correlation)` on purpose: the private method is the real correlation
-      # logic, and reimplementing it here would only approximate it.
-      def last_advancing_event(runtime, interpreter, process_manager, correlation)
-        entry = runtime.registry.saga_log.reverse_each.find do |row|
-          row[:process_manager] == process_manager.name && row[:instance] == correlation &&
-            row[:advanced] && row[:on] != Runtime::SagaInterpreter::REFUSED
-        end
-        return nil unless entry
-
-        runtime.events.reverse_each.find do |event|
-          event.name == entry[:on] && interpreter.send(:saga_correlation, process_manager, event) == correlation
-        end
-      end
-
-      # One correlation's redelivery check, split out of `check_saga_idempotency`.
-      # The `saga_log` mark/restore stays here so it sits beside the `advance` it guards.
-      def check_one_saga_redelivery(runtime, interpreter, domain_name, process_manager, anchor,
-                                    correlation, saga, redelivery)
-        # rubocop:disable-next Metrics/BlockLength
-        Dir.mktmpdir("hecks-self-consistency-saga") do |tmp|
-          writer = guarded_heki(aggregate: anchor, root: tmp, settings: { domain: domain_name })
-          writer.save_saga(process_manager: process_manager.name, correlation: correlation.to_s,
-                           state: saga[:state], memory: saga[:memory], completed_compensations: [])
-
-          rehydrated = guarded_heki(aggregate: anchor, root: tmp, settings: { domain: domain_name })
-                       .each_saga.find { |_pm, corr, *| corr == correlation.to_s }
-          next unless rehydrated
-
-          _pm, _corr, state, memory, compensations = rehydrated
-          before = { state: state, memory: deep_stringify_keys(memory) }
-
-          saga_instances = runtime.registry.saga_instances[process_manager.name]
-          original       = saga_instances[correlation]
-
-          # `advance` appends to `saga_log` (shared by reference with the primary trace);
-          # the tail is sliced back off in `ensure` so the probe does not leak into it.
-          saga_log      = runtime.registry.saga_log
-          saga_log_mark = saga_log.size
-          begin
-            saga_instances[correlation] = { state: state, memory: memory, completed_compensations: compensations || [] }
-            interpreter.advance(redelivery, domain_name, only: process_manager)
-
-            after       = saga_instances[correlation]
-            after_shape = after && { state: after[:state], memory: deep_stringify_keys(after[:memory]) }
-            next if after_shape == before
-
-            { field: "saga_redelivery_idempotency", domain: domain_name, process_manager: process_manager.name,
-              correlation: correlation, on: redelivery.name, before: before, after: after_shape }
-          ensure
-            saga_log.slice!(saga_log_mark..) if saga_log.size > saga_log_mark
-
-            if original
-              saga_instances[correlation] = original
-            else
-              saga_instances.delete(correlation)
-            end
-          end
-        end
-      end
-
       # Folds `entries` into `writer`, then reads back through a fresh `Heki` instance so the
       # result comes from disk rather than the writer's cache. Calling it twice on one writer
       # replays the journal a second time.
@@ -314,26 +129,6 @@ module Hecks
           ]
         end
       end
-
-      # Recurses via `#[]` rather than `#to_h`, which would materialize nested values away.
-      # `seen` compares by identity: a live state and an event payload can share one object,
-      # while two equal but distinct value objects are still two round trips to prove.
-      def walk_value_objects(node, found, seen, aggregate)
-        case node
-        when Runtime::Value
-          return if seen[node]
-
-          seen[node] = true
-          found << [node, aggregate]
-          node.value_object.attributes.each do |attribute|
-            walk_value_objects(node[attribute.name], found, seen, aggregate)
-          end
-        when Hash
-          node.each_value { |value| walk_value_objects(value, found, seen, aggregate) }
-        when Array
-          node.each { |value| walk_value_objects(value, found, seen, aggregate) }
-        end
-      end
     end
   end
 end

data/lib/hecks/fuzzing/sequence_generator/adversary/argument_mutations.rb

@@ -0,0 +1,116 @@
+require_relative "../../invalid_value_generator"
+require_relative "../../value_generator"
+require_relative "../../../runtime/value"
+
+module Hecks
+  module Fuzzing
+    class SequenceGenerator
+      module Adversary
+        # The mutations aimed at a step's other arguments: a routing key, a nulled single-field
+        # value object, and an omitted mapped argument.
+        module ArgumentMutations
+          private
+
+          # Not applied over a routed `to:` from `deep_entity_addressing!`; overwriting it would
+          # contradict that step's note.
+          def routing_key_applicable?(args, _entry, _catalog) = !args.key?("to")
+
+          def apply_routing_key!(args, entry, _catalog)
+            key   = ROUTING_KEYS.sample(random: @random)
+            shape = ROUTING_SHAPES.sample(random: @random)
+            args[key] =
+              case shape
+              when "null"   then nil
+              when "scalar" then routing_scalar(args, entry)
+              else               routing_object(args, entry)
+              end
+            { "mutation" => "routing_key", "bug" => "BUG#7/#16/#8", "key" => key, "shape" => shape,
+              "declared" => !entry[:command].attribute(key).nil? }
+          end
+
+          # This step's own parent id, an out-of-range Integer, or a minted id nothing holds.
+          def routing_scalar(args, entry)
+            case @random.rand(3)
+            when 0 then parent_scalar_of(args, entry)
+            when 1 then ValueGenerator::INTEGER_EDGE_CASES.sample(random: @random)
+            else        ValueGenerator.random_id(@random)
+            end
+          end
+
+          def routing_object(args, entry)
+            entities = (entry[:chain] || []).map { |piece| ValueGenerator.scalar_of(args[(piece.identified_by || :id).to_s]) }
+            # Half the time one identity too many, a depth the verb lacks, which both engines must
+            # refuse alike.
+            entities << ValueGenerator.random_id(@random) if @random.rand(2).zero?
+            { "aggregate" => parent_scalar_of(args, entry), "entities" => entities }
+          end
+
+          def parent_scalar_of(args, entry)
+            key = (entry[:aggregate].identified_by || :id).to_s
+            args.key?(key) ? ValueGenerator.scalar_of(args[key]) : identity_scalar_of(entry[:aggregate], args)
+          end
+
+          def null_value_object_applicable?(args, entry, _catalog) = value_object_targets(args, entry).any?
+
+          def value_object_targets(args, entry)
+            aggregate = entry[:aggregate]
+            entry[:command].attributes.reject { |attribute| attribute.list? || attribute.reference? }
+                           .select { |attribute| args.key?(attribute.name.to_s) }
+                           .filter_map do |attribute|
+              value_object = Runtime::Value.value_object_for(aggregate, attribute.type.to_s)
+              [attribute, value_object] if value_object&.sole_attribute
+            end
+          end
+
+          def apply_null_value_object!(args, entry, _catalog)
+            targets = value_object_targets(args, entry)
+            closed  = targets.select { |_, value_object| value_object.closed_set? }
+            attribute, value_object = (closed.empty? ? targets : closed).sample(random: @random)
+            shape = VALUE_OBJECT_SHAPES.sample(random: @random)
+            args[attribute.name.to_s] = shape == "null" ? nil : {}
+            { "mutation" => "null_value_object", "bug" => "BUG#14", "argument" => attribute.name.to_s,
+              "value_object" => value_object.hecks_name, "closed_set" => value_object.closed_set? == true,
+              "shape" => shape }
+          end
+
+          def omit_mapped_argument_applicable?(args, entry, _catalog) = mapped_argument_targets(args, entry).any?
+
+          # An append's mapped source arguments, or a plain creating command's non-identity
+          # attributes; never an identity head.
+          def mapped_argument_targets(args, entry)
+            mapped = mapped_names(entry)
+            heads  = identity_heads_of(entry)
+            needed = needed_facts_of(entry)
+            entry[:command].attributes.select do |attribute|
+              name = attribute.name.to_s
+              mapped.include?(name) && args.key?(name) && !heads.include?(name) && !needed.include?(name)
+            end
+          end
+
+          # The names of the arguments an append maps into its element, or every attribute of a
+          # plain creating command.
+          def mapped_names(entry)
+            command = entry[:command]
+            mapped  = appended_sources(command)
+            return mapped unless mapped.empty? && !entry.key?(:entity) && command.creates?
+
+            command.attributes.map { |attribute| attribute.name.to_s }
+          end
+
+          # The argument names the command's appends take their element fields from.
+          def appended_sources(command)
+            command.mutations.select { |mutation| mutation.op == :append }
+                   .flat_map { |mutation| mutation.source.values.grep(Symbol).map(&:to_s) }
+          end
+
+          def apply_omit_mapped_argument!(args, entry, _catalog)
+            attribute = mapped_argument_targets(args, entry).sample(random: @random)
+            args.delete(attribute.name.to_s)
+            { "mutation" => "omit_mapped_argument", "bug" => "BUG#12", "argument" => attribute.name.to_s,
+              "optional" => attribute.optional? == true }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/sequence_generator/adversary/caller_draw.rb

@@ -0,0 +1,68 @@
+require_relative "../../value_generator"
+
+module Hecks
+  module Fuzzing
+    class SequenceGenerator
+      module Adversary
+        # The caller a role-gated command is dispatched under: drawn per `role_draw:`, or parked by
+        # the refusal-precedence mutation.
+        module CallerDraw
+          private
+
+          def role_draw? = @role_draw.positive?
+
+          # `[caller, note]`: the caller StepBuilder binds around the dispatch (nil for the
+          # unchecked control) and the note for the step's `"adversarial"` metadata. A caller
+          # parked by `refusal_precedence` wins; an ungated command draws nothing.
+          def caller_draw!(entry, catalog)
+            return take_precedence_caller if @precedence_caller
+
+            role = entry[:command].role.to_s
+            return [nil, nil] if !role_draw? || role.empty? || @random.rand >= @role_draw
+
+            drawn_caller(role, catalog)
+          end
+
+          def take_precedence_caller
+            caller = @precedence_caller
+            @precedence_caller = nil
+            [caller, nil]
+          end
+
+          def drawn_caller(role, catalog)
+            shapes = CALLER_SHAPES.dup
+            shapes.delete("actor_known") if @granted[role].empty?
+            shape  = shapes.sample(random: @random)
+            caller = caller_for_shape(shape, role, catalog)
+            note   = { "mutation" => "caller_role", "angle" => "ANGLE-5", "shape" => shape, "gated_role" => role }
+            [caller, caller ? note.merge(caller) : note]
+          end
+
+          def caller_for_shape(shape, role, catalog)
+            case shape
+            when "matching"      then { "role" => role }
+            when "mismatched"    then { "role" => other_role(role, catalog) }
+            when "actor_known"   then { "role" => role, "actor_id" => @granted[role].sample(random: @random) }
+            when "actor_unknown" then { "role" => role, "actor_id" => ValueGenerator.random_id(@random) }
+            end
+          end
+
+          # Another declared role when there is one (a real wrong hat), else a role none names.
+          def other_role(role, catalog)
+            others = catalog[:roles] - [role]
+            others.empty? ? UNKNOWN_ROLE : others.sample(random: @random)
+          end
+
+          # Aims a grant at a role some command declares; random role text would make `actor_known`
+          # unreachable. Does nothing without the role draw.
+          def steer_grant!(args, entry, catalog)
+            return unless role_draw? && catalog[:grant_verbs].include?(entry[:verb]) && catalog[:roles].any?
+            return unless args.key?("role_name")
+
+            args["role_name"] = { "value" => catalog[:roles].sample(random: @random) }
+          end
+        end
+      end
+    end
+  end
+end