hecks 3.5.0 → 3.7.0

data/lib/hecks/fuzzing/properties.rb

@@ -11,6 +11,13 @@ require_relative "properties/dispatch_and_mutations"
 require_relative "properties/invariants_and_aggregation"
 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
@@ -27,110 +34,14 @@ module Hecks
       extend InvariantsAndAggregation
       extend Corrections
       extend Outbox
+      extend PolicyWiring
+      extend References
+      extend RoleChecks
+      extend ReadModelNames
+      extend ReadModels
 
       module_function
 
-      # Which language feature each property is answerable for — exhaustive of
-      # what would go unchecked without it, not of everything its body touches.
-      FEATURE_COVERAGE = {
-        lifecycle_values_are_declared:                    %w[Aggregate#state_field Aggregate#state_start Aggregate#transitions
-                                                             Entity#state_field Entity#state_start Entity#transitions],
-        saga_advances_follow_declared_handlers:           %w[Handler#from_state Handler#to_state Handler#event_type],
-        query_answers_match_reference:                    %w[Query#wheres Query#order_field Query#order_way Query#limit],
-        paging_offset_partitions_correctly:               %w[Query#options],
-        authorize_scopes_or_refuses:                      %w[Query#options],
-        guard_refusals_are_declared:                      %w[Command#givens Command#ensures Command#needs],
-        lifecycle_guard_and_given_violations_are_refused: %w[Command#from Aggregate#preconditions Entity#preconditions],
-        # Dispatch#command_name/with_spec aren't claimable feature names — the
-        # coverage walk only reaches one level of entity nesting and Dispatch
-        # sits two deep — but this property still checks the real behavior
-        # (dispatch_args) those names would have covered.
-        dispatch_binding_fidelity:                        %w[Handler#dispatches Policy#with_spec],
-        mutations_match_recompute:                        %w[Command#mutations],
-        sagas_rehydrate_cleanly:                          %w[ProcessManager#states ProcessManager#correlates_by
-                                                             ProcessManager#starts_on ProcessManager#ends_on],
-        fanout_dispatches_once_per_matching_row:          %w[Policy#for_each Policy#where],
-        aggregation_matches_recompute:                    %w[ReadModel#count ReadModel#median_field ReadModel#sum_field
-                                                             ReadModel#avg_field ReadModel#min_field ReadModel#max_field
-                                                             ReadModel#percentile_field ReadModel#percentile_at
-                                                             ReadModel#any_field ReadModel#all_field],
-        stored_records_satisfy_declared_invariants:       %w[Aggregate#invariants Entity#invariants],
-        group_by_matches_recompute:                       %w[ReadModel#group_by],
-        # A runtime door, not a grammar construct — `Dispatcher#dry_run?` is not
-        # a word a bluebook declares. Listed empty rather than omitted, so every
-        # property still names what it is answerable for.
-        dry_runs_leave_no_trace:                          [],
-        # Another runtime door, not a grammar construct — same reasoning as
-        # dry_runs_leave_no_trace above.
-        outbox_rows_match_reactions:                      [],
-        # Reads command.mutations for :corrects ops — the same list
-        # mutations_match_recompute reads, for a different question.
-        corrections_reference_an_emitted_event:           %w[Command#mutations],
-        # No feature string exists for what this reads: an argument's own
-        # `relationship` (Argument is a value object, outside the meta-domain
-        # walk). Its declaration side, `Query#options`, is already claimed by
-        # authorize_scopes_or_refuses.
-        commands_respect_tenant_scope:                    []
-      }.freeze
-
-      # Features a replay could never observe violated, because construction
-      # makes the violation impossible to produce — not untested, but
-      # unfalsifiable. Each entry names the runtime path that guarantees it;
-      # add one only after reading and confirming that path (mirrors the
-      # discipline spec/fuzzing/meta_domain_coverage_spec.rb's KNOWN_GAPS demands
-      # in the other direction).
-      GUARANTEED_BY_CONSTRUCTION = {
-        "Aggregate#attributes"    => "every field's pattern/closed-set/type passes through Value.build's one coercion " \
-                                     "door (value/coercion.rb#check_patterns, value/admission.rb) before it can exist " \
-                                     "— a stored value that violated its own declared shape was never producible to " \
-                                     "begin with",
-        "Aggregate#value_objects" => "the shape being coerced above — same door, same guarantee",
-        # S17, ADR 0026 — saga_advances_follow_declared_handlers already walks
-        # this list to find event_type/from_state/to_state; same door, same guarantee.
-        "ProcessManager#handlers" => "saga_advances_follow_declared_handlers already walks this list to find " \
-                                     "event_type/from_state/to_state — same door, same guarantee",
-        "Aggregate#identified_by" => "CommandInterpreter's data-driven dispatch order refuses AlreadyExists " \
-                                     "(command_interpreter.rb, command.creates?) for every creating command uniformly, " \
-                                     "before a duplicate id can ever be stored — collision is refused at the door, not " \
-                                     "produced and later caught",
-        "Entity#identified_by"    => "EntityElement.check_entity_collision (runtime/entity_element.rb, moved there " \
-                                     "BUG#145 so both call sites share it) checks Array(current) against every part " \
-                                     "of the entity's own identity before an append can land — MutationApplier#" \
-                                     "entity_element's aggregate-owned call (Workspace.boards, on both branches " \
-                                     "identity arrives by: caller-supplied, or composite) AND EntityElement#" \
-                                     "appended_to_element's entity-owned, nested-one-hop-further call (Board.cards — " \
-                                     "unconditional, no auto-mint branch exists at that depth) — the same " \
-                                     "AlreadyExists refusal Aggregate#identified_by gets above, one or two levels " \
-                                     "down. Auto-minted (aggregate-owned) entities never reach the check " \
-                                     "(current.size + 1 can't repeat unless something remove:s from the list between " \
-                                     "mints, which no real domain does today — see the comment on #entity_element " \
-                                     "itself)",
-        "Command#attributes"      => "command arguments are coerced through the SAME Value.build door as any other " \
-                                     "attribute — an accepted dispatch's own args already passed pattern/admits/invariant checks",
-        "Command#emits"           => "CommandRules::Emission#emit iterates command.emits ITSELF to construct every " \
-                                     "announced Event (command_rules/emission.rb) — there is no other path to emit, so " \
-                                     "a command can never announce a name its own declaration doesn't list",
-        "Query#attributes"        => "query arguments are coerced through the same Value.build door — same guarantee as " \
-                                     "Command#attributes",
-        "Query#returns"           => "every row a port answers is built as the returned value object by Value.build " \
-                                     "(QueryInterpreter#shaped) before it enters the domain — an answer of any other " \
-                                     "shape is refused, so none can be accepted",
-        "Entity#attributes"       => "same coercion door, one level in — an entity's own attributes are Value-typed exactly " \
-                                     "the way an aggregate's are",
-        "ValueObject#attributes"  => "the shape Value.build enforces IS this declaration — the guarantee and the " \
-                                     "feature are the same fact seen from two sides",
-        "ValueObject#invariants"  => "run inside the SAME coercion call (coercion.rb, before construction returns) " \
-                                     "that pattern-checks a VO's fields — a VO whose invariant did not hold could not " \
-                                     "finish being built",
-        "ValueObject#rows"        => "closed-set membership is checked in value/admission.rb, the second half of the same " \
-                                     "one construction door",
-        # S17, ADR 0026 — Member is a genuine entity, so this reads Member#pairs,
-        # not Member#shape. ValueObject#members is the same fact ValueObject#rows
-        # counts, seen from the other side.
-        "ValueObject#members"     => "the members list IS what ValueObject#rows counts — same door, same guarantee",
-        "Member#pairs"            => "one level into ValueObject#rows — same door"
-      }.freeze
-
       # Runs the standard property battery over one replayed history — all but
       # determinism, which replays twice itself and so is checked separately.
       #
@@ -138,24 +49,7 @@ module Hecks
       # @return [Hash{Symbol => true, String}] each property name mapped to `true`
       #   (passed) or a message string naming what broke
       def check(history)
-        { lifecycle_values_are_declared:                    lifecycle_values_are_declared(history),
-          saga_advances_follow_declared_handlers:           saga_advances_follow_declared_handlers(history),
-          query_answers_match_reference:                    query_answers_match_reference(history),
-          guard_refusals_are_declared:                      guard_refusals_are_declared(history),
-          sagas_rehydrate_cleanly:                          sagas_rehydrate_cleanly(history),
-          fanout_dispatches_once_per_matching_row:          fanout_dispatches_once_per_matching_row(history),
-          aggregation_matches_recompute:                    aggregation_matches_recompute(history),
-          stored_records_satisfy_declared_invariants:       stored_records_satisfy_declared_invariants(history),
-          group_by_matches_recompute:                       group_by_matches_recompute(history),
-          paging_offset_partitions_correctly:               paging_offset_partitions_correctly(history),
-          lifecycle_guard_and_given_violations_are_refused: lifecycle_guard_and_given_violations_are_refused(history),
-          authorize_scopes_or_refuses:                      authorize_scopes_or_refuses(history),
-          commands_respect_tenant_scope:                    commands_respect_tenant_scope(history),
-          dispatch_binding_fidelity:                        dispatch_binding_fidelity(history),
-          mutations_match_recompute:                        mutations_match_recompute(history),
-          dry_runs_leave_no_trace:                          dry_runs_leave_no_trace(history),
-          corrections_reference_an_emitted_event:           corrections_reference_an_emitted_event(history),
-          outbox_rows_match_reactions:                      outbox_rows_match_reactions(history) }
+        PROPERTY_NAMES.to_h { |name| [name, public_send(name, history)] }
       end
     end
   end

data/lib/hecks/fuzzing/qa_settings.rb

@@ -55,25 +55,10 @@ module Hecks
       # @raise [ArgumentError] if `raw` is missing a required key, declares an unknown
       #   key, or gives a value the wrong type for its dial
       def initialize(raw, path)
-        missing = EXPECTED_TYPES.keys - raw.keys
-        raise ArgumentError, "#{path} is missing #{missing.sort.join(', ')}" if missing.any?
-
-        extra = raw.keys - EXPECTED_TYPES.keys
-        if extra.any?
-          raise ArgumentError,
-                "#{path} declares unknown key(s) #{extra.sort.join(', ')} — " \
-                "no QaDial row of the Vocabulary chapter declares them"
-        end
-
+        check_keys!(raw, path)
         EXPECTED_TYPES.each do |key, expected|
           value = raw.fetch(key)
-          expected_classes = Array(expected)
-          unless expected_classes.any? { |klass| value.is_a?(klass) }
-            raise ArgumentError,
-                  "#{path}: #{key} must be a #{expected_classes.map(&:name).join(' or ')}, " \
-                  "got #{value.class} (#{value.inspect})"
-          end
-
+          check_type!(path, key, expected, value)
           instance_variable_set(:"@#{key}", value)
         end
 
@@ -83,6 +68,27 @@ module Hecks
 
       private
 
+      def check_keys!(raw, path)
+        missing = EXPECTED_TYPES.keys - raw.keys
+        raise ArgumentError, "#{path} is missing #{missing.sort.join(", ")}" if missing.any?
+
+        extra = raw.keys - EXPECTED_TYPES.keys
+        return unless extra.any?
+
+        raise ArgumentError,
+              "#{path} declares unknown key(s) #{extra.sort.join(", ")} — " \
+              "no QaDial row of the Vocabulary chapter declares them"
+      end
+
+      def check_type!(path, key, expected, value)
+        expected_classes = Array(expected)
+        return if expected_classes.any? { |klass| value.is_a?(klass) }
+
+        raise ArgumentError,
+              "#{path}: #{key} must be a #{expected_classes.map(&:name).join(" or ")}, " \
+              "got #{value.class} (#{value.inspect})"
+      end
+
       # YAML cannot spell a Symbol value, and IsolatedBoot case-matches adapters by symbol.
       def symbolize_adapter_parity_pairs!(path)
         @adapter_parity_pairs = @adapter_parity_pairs.to_h do |mode, pair|

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

@@ -0,0 +1,78 @@
+module Hecks
+  module Fuzzing
+    module Replay
+      # Independent recomputation of what each `for_each` policy should have fanned out over.
+      module FanOut
+        # What one event's fan-out findings are computed against.
+        Context = Struct.new(:runtime, :snapshot, :reactions_since)
+
+        # One finding per (event, for_each policy) pair, independent of
+        # `PolicyInterpreter#deliver_for_each`, answered via `Ports::Query::InMemory`
+        # directly rather than `QueryInterpreter`, so this stays blind to nothing the
+        # fan-out feature adds. `expected_row_ids` is `nil` when `where` did not hold.
+        def fan_out_findings(runtime, snapshot, announced, reactions_since)
+          context = Context.new(runtime, snapshot, reactions_since)
+          announced.each_with_object([]) do |event, findings|
+            # `event.aggregate` is domain-qualified ("Banking::Account"); split the same
+            # two ways `PolicyInterpreter#policies_for` does.
+            domain = event.aggregate.to_s.split("::").first
+            bluebook = runtime.registry.bluebook(domain)
+            next unless bluebook
+
+            fanning_policies(bluebook, event).each do |policy|
+              findings << fan_out_finding(context, policy, event, domain)
+            end
+          end
+        end
+
+        # The bluebook's `for_each` policies that react to `event`.
+        def fanning_policies(bluebook, event)
+          emitting = Naming.demodulise(event.aggregate)
+          bluebook.policies.select do |policy|
+            policy.fans_out? && policy.event_name == event.name &&
+              (policy.event_qualifier.nil? || policy.event_qualifier == emitting)
+          end
+        end
+
+        # Builds one fan-out finding, comparing one `for_each` policy's independently
+        # recomputed expected rows against what actually reacted for one event.
+        def fan_out_finding(context, policy, event, domain)
+          payload = event.payload.transform_keys(&:to_sym)
+          held = policy.where.to_s.empty? || Bluebook::Expression::Evaluator.call(policy.where, {}, payload)
+          expected = held ? expected_fan_out_rows(context.runtime, context.snapshot, policy, domain, payload) : nil
+
+          { policy: policy.name, on: event.name, expected_row_ids: expected,
+            actual_row_ids: reacted_rows(context.reactions_since, policy, event) }
+        end
+
+        # The rows the reaction log shows `policy` dispatching to for `event`.
+        def reacted_rows(reactions_since, policy, event)
+          reactions_since.select { |r| r[:policy] == policy.name && r[:on] == event.name }
+                         .filter_map { |r| r[:for_row] }
+        end
+
+        # `policy.for_each`'s declared query, answered against the pre-dispatch snapshot
+        # (the real fan-out's query runs before its own dispatched commands can mutate
+        # anything it would match, so this must read the same "before" state). A `Symbol`
+        # where-value binds to the triggering event's own payload; a literal is as declared.
+        def expected_fan_out_rows(runtime, snapshot, policy, domain, payload)
+          query_domain, aggregate_name, query_name = policy.for_each_route(domain)
+          query = for_each_query(runtime, query_domain, aggregate_name, query_name)
+          return [] unless query
+
+          rows = snapshot[[query_domain, aggregate_name]] || {}
+          matched = rows.select do |_id, state|
+            query.wheres.all? { |clause| clause_holds?(clause, state, payload) }
+          end
+
+          matched.keys.map(&:to_s).sort
+        end
+
+        # The declared query a `for_each` policy names, or nil.
+        def for_each_query(runtime, query_domain, aggregate_name, query_name)
+          runtime.registry.bluebook(query_domain)&.aggregate(aggregate_name)&.query(query_name)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+require_relative "../../query_specification/common/comparators"
+require_relative "../../query_specification/common/where_clause"
+require_relative "../../query_specification/field_path"
+require_relative "../../ports/query/in_memory"
+
+module Hecks
+  module Fuzzing
+    module Replay
+      # Answers the ad hoc `{aggregate:, field:, op:, value:}` filter steps that bypass the
+      # declared query DSL.
+      module Filters
+        # Mirrors QuerySpecification::Common::COMPARATORS, not the Rust
+        # kernel's own comparator enum, which is missing `none_in_state` and has drifted.
+        FILTER_COMPARATORS = Hecks::QuerySpecification::Common::COMPARATORS.map(&:to_s).freeze
+
+        # Answers one ad hoc filter step, the mirror image of kernel/cli.rs's own
+        # `run_filter`, calling the same production `Ports::Query::InMemory` rather than
+        # re-deriving comparator behavior by hand. Sorted by id ascending regardless,
+        # since an ad hoc filter declares no order of its own.
+        #
+        # @raise [Bluebook::Expression::EvaluationError] if `op` or `"aggregate"` is unknown
+        def run_filter(runtime, filter)
+          check_comparator!(filter["op"].to_s)
+
+          domain_name, aggregate = filter_aggregate(runtime, filter["aggregate"].to_s)
+          clause  = filter_clause(filter)
+          records = runtime.registry.repository(domain_name, aggregate).all
+
+          rows_by_id(records.select { |record| clause_holds?(clause, record, {}) })
+        end
+
+        # A malformed ad-hoc ask is a fault (C8.3), not a bare RuntimeError.
+        def check_comparator!(comparator)
+          return if FILTER_COMPARATORS.include?(comparator)
+
+          raise Bluebook::Expression::EvaluationError, "unknown query comparator #{comparator.inspect}"
+        end
+
+        def filter_clause(filter)
+          QuerySpecification::Common::WhereClause.new(field: filter["field"].to_s, op: filter["op"].to_s, value: filter["value"])
+        end
+
+        # The records as `{id:, **state}` rows, sorted by id ascending.
+        def rows_by_id(records)
+          records.sort_by { |record| record.id.to_s }.map { |record| { id: record.id }.merge(record.state) }
+        end
+
+        # The domain name and aggregate a filter's `"Domain::Aggregate"` reference names.
+        #
+        # @raise [Bluebook::Expression::EvaluationError] if no such aggregate is loaded
+        def filter_aggregate(runtime, aggregate_ref)
+          domain_name, aggregate_name = aggregate_ref.split("::", 2)
+          aggregate = runtime.registry.bluebook(domain_name)&.aggregate(aggregate_name)
+          raise Bluebook::Expression::EvaluationError, "unknown aggregate #{aggregate_ref.inspect}" unless aggregate
+
+          [domain_name, aggregate]
+        end
+
+        # Whether `subject`'s value at the clause's field satisfies the clause, `args` binding
+        # any Symbol value.
+        def clause_holds?(clause, subject, args)
+          held = Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(subject, clause.field))
+          Ports::Query::InMemory.holds?(clause, held, args)
+        end
+
+        # Builds the `refusals` entry's own "verb" column for a refused ad hoc filter,
+        # which carries no real verb to report.
+        def filter_label(filter) = "filter #{filter["aggregate"]}.#{filter["field"]} #{filter["op"]}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+module Hecks
+  module Fuzzing
+    module Replay
+      # Replays a step's guard read-only, before the real dispatch can mutate anything, so the
+      # outcome can be compared with what the dispatch actually did.
+      module GuardCheck
+        # The command a guard check is about, and where it lives.
+        Target = Struct.new(:domain, :aggregate_name, :command_name, :aggregate, :command)
+
+        module_function
+
+        # Resolves the record (if any) this step's guard should be checked against, and
+        # replays enforce_givens then admissible_transition, in that order, to mirror
+        # the real DISPATCH_ORDER. `nil` for anything out of scope.
+        def build(runtime, verb, args)
+          target = target_for(runtime, verb)
+          return nil unless target
+
+          id = Replay.identity_for(target.aggregate, target.command, args)
+          record = id && runtime.registry.repository(target.domain, target.aggregate).find(id)
+          return nil unless record
+
+          { verb: verb, domain: target.domain, aggregate: target.aggregate_name, command: target.command_name,
+            id: id, **recomputation(runtime, target, record, args) }
+        rescue StandardError
+          nil
+        end
+
+        # The aggregate-level command `verb` names, when it has a guard worth checking.
+        def target_for(runtime, verb)
+          domain_name, aggregate_name, command_name = Naming.split_verb(verb)
+          return nil unless command_name && !command_name.include?(".")
+
+          aggregate = runtime.registry.bluebook(domain_name)&.aggregate(aggregate_name)
+          command   = aggregate&.command(command_name)
+          return nil unless checkable?(aggregate, command)
+
+          Target.new(domain_name, aggregate_name, command_name, aggregate, command)
+        end
+
+        def checkable?(aggregate, command)
+          aggregate && command && !command.creates? && guarded?(aggregate, command)
+        end
+
+        # A transition-only guard (no per-command `from:`/`given`, only an aggregate
+        # `lifecycle` block naming this command) still counts as something to check,
+        # now that `admissible_transition` is reproduced.
+        def guarded?(aggregate, command)
+          has_transition = aggregate.lifecycle&.transitions_for(command.hecks_name)&.any?
+          !(command.givens.empty? && !command.from && !has_transition)
+        end
+
+        # What an independent run of the guard says about the step.
+        #
+        # Real dispatch normalizes args (step_normalize_args) before it ever reaches
+        # enforce_givens, coercing a bare scalar like "white" into its command's declared
+        # value-object shape. Skipping that here would hand enforce_givens the raw fuzzed
+        # shape instead, and a `given` comparing a normalized field against it would walk a
+        # path a String happens to answer (a substring lookup) rather than the refusal real
+        # dispatch raises. `send` reaches the interpreter's own private coercion (the same
+        # idiom SelfConsistency#last_advancing_event uses for `saga_correlation`) rather than
+        # reimplementing it here.
+        def recomputation(runtime, target, record, args)
+          rules = Runtime::CommandRules.new(runtime.registry)
+          interpreter = Runtime::CommandInterpreter.new(runtime.registry, rules: rules)
+          normalized_args = interpreter.send(:normalize_args, target.aggregate, target.command, args)
+          kind = refusal_class_name(rules, target, record, normalized_args)
+          { recomputed_refused: !kind.nil?, recomputed_kind: kind }
+        end
+
+        # The class name of the guard refusal the independent run raises, or nil when it admits.
+        def refusal_class_name(rules, target, record, normalized_args)
+          rules.enforce_givens(record.dup, target.command, normalized_args, domain: target.domain, declaring: target.aggregate)
+
+          # A second, separate DISPATCH_ORDER step: the aggregate's own `lifecycle`
+          # transition guard is a wholly different method from enforce_givens' own
+          # per-command `from:` check, called only when enforce_givens didn't already refuse.
+          # It reads only the record's own lifecycle field and the command's declared
+          # transitions, never `args`, so it needs no normalized input of its own.
+          rules.admissible_transition(target.aggregate, target.command, record.dup)
+          nil
+        rescue *GUARD_REFUSAL_CLASSES => e
+          e.class.name
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,117 @@
+module Hecks
+  module Fuzzing
+    module Replay
+      # Snapshots the entity element a mutation step addresses before dispatch, and re-reads it
+      # after, so the mutation can be diffed against an independent recomputation.
+      module MutationTrace
+        # The entity command a trace is about, and where it lives.
+        Target = Struct.new(:domain, :aggregate_name, :command_name, :aggregate, :entity, :command)
+
+        # The element a mutation step addresses, found in its parent's `list_of` attribute.
+        Located = Struct.new(:parent_id, :list_attr, :wants, :element)
+
+        module_function
+
+        # Scoped to entity-dispatched commands only, the one place `append`/`remove`/
+        # `multiply`/`clamp` act on an entity's own attributes. `nil` for anything out of
+        # scope: an aggregate-level command, no mutations, or unresolvable identity args.
+        def build(runtime, verb, args)
+          target = target_for(runtime, verb)
+          return nil unless target
+
+          args = normalized_args(runtime, target, args)
+          located = locate_element(runtime, target, args)
+          return nil unless located
+
+          { verb: verb, domain: target.domain, aggregate: target.aggregate_name, command: target.command_name,
+            parent_id: located.parent_id, list_attr: located.list_attr.name, element_wants: located.wants,
+            before: Runtime::Value.materialize(located.element), args: args }
+        rescue StandardError
+          nil
+        end
+
+        # The entity command `verb` names, when it declares mutations.
+        def target_for(runtime, verb)
+          domain_name, aggregate_name, command_name = Naming.split_verb(verb)
+          return nil unless command_name&.include?(".")
+
+          aggregate = runtime.registry.bluebook(domain_name)&.aggregate(aggregate_name)
+          return nil unless aggregate
+
+          entity, command = entity_command(aggregate, command_name)
+          return nil unless mutates?(command)
+
+          Target.new(domain_name, aggregate_name, command_name, aggregate, entity, command)
+        end
+
+        def mutates?(command) = command&.mutations&.any?
+
+        # The entity and command a dotted `Entity.Command` path names under `aggregate`.
+        def entity_command(aggregate, command_name)
+          entity_name, entity_command_name = command_name.split(".", 2)
+          entity = aggregate.entities.find { |candidate| candidate.hecks_name == entity_name }
+          [entity, entity&.command(entity_command_name)]
+        end
+
+        # Same idiom as GuardCheck: real dispatch normalizes args
+        # (step_normalize_args) before apply_mutations ever runs, coercing a declared
+        # payload attribute into its command's shape — a composite argument's own
+        # `Value.build` fills that shape's declared defaults along the way. Recomputing
+        # a mutation against the raw fuzzed args instead would disagree with real
+        # dispatch whenever a caller omitted a defaulted field, the same false-divergence
+        # shape GuardCheck guards against for the guard check.
+        def normalized_args(runtime, target, args)
+          interpreter = Runtime::CommandInterpreter.new(runtime.registry, rules: Runtime::CommandRules.new(runtime.registry))
+          interpreter.send(:normalize_args, target.aggregate, target.command, args)
+        end
+
+        # Finds the stored element the step's identity args address, or nil.
+        def locate_element(runtime, target, args)
+          parent_id = Replay.identity_for(target.aggregate, target.command, args)
+          record = parent_id && runtime.registry.repository(target.domain, target.aggregate).find(parent_id)
+          list_attr = record && list_attribute(target)
+          wants = list_attr && element_wants(target, args)
+          element = wants && find_element(record.state[list_attr.name], wants)
+          element && Located.new(parent_id, list_attr, wants, element)
+        end
+
+        def list_attribute(target)
+          target.aggregate.attributes.find { |a| a.list? && a.type.to_s == target.entity.hecks_name }
+        end
+
+        # The `[head, value]` identity pairs the args give for the entity, or nil when an
+        # identity argument is missing.
+        def element_wants(target, args)
+          target.entity.identity_paths.map do |path|
+            head = path.to_s.split(".").first.to_sym
+            raw  = args[head]
+            return nil if raw.nil?
+
+            [head, Runtime::Value.for_attribute(target.aggregate, target.entity.attribute(head), raw)]
+          end
+        end
+
+        def find_element(items, wants)
+          Array(items).find { |element| wants.all? { |head, want| element[head] == want } }
+        end
+
+        # Re-locates the same element by identity, not position, since a mutation could
+        # have changed the array's own length or order. `nil` if it vanished.
+        def read_after(runtime, trace)
+          record = parent_record(runtime, trace)
+          return nil unless record
+
+          element = find_element(record.state[trace[:list_attr]], trace[:element_wants])
+          element && Runtime::Value.materialize(element)
+        rescue StandardError
+          nil
+        end
+
+        def parent_record(runtime, trace)
+          aggregate = runtime.registry.bluebook(trace[:domain])&.aggregate(trace[:aggregate])
+          aggregate && runtime.registry.repository(trace[:domain], aggregate).find(trace[:parent_id])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+module Hecks
+  module Fuzzing
+    module Replay
+      # What a session reads off the runtime: the final history and the pre-dispatch snapshot a
+      # `for_each` fan-out is checked against. Mixed into `Session`.
+      module Observation
+        private
+
+        def observed_history
+          { 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, 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,
+            bluebooks: @runtime.registry.bluebooks.dup }
+        end
+
+        def events
+          @runtime.events.map { |event| { name: event.name, aggregate: event.aggregate, id: event.id, payload: event.payload } }
+        end
+
+        # The live process-manager store, materialised to inert data (`{ pm_name =>
+        # { correlation => { state:, memory: } } }`), captured here because the
+        # runtime goes out of scope with the boot and the Memory rebind leaves no
+        # real saga store for Properties.sagas_rehydrate_cleanly to read otherwise.
+        def saga_instances
+          @runtime.registry.saga_instances.each_with_object({}) do |(pm_name, conversations), out|
+            out[pm_name] = conversations.each_with_object({}) do |(correlation, instance), rows|
+              rows[correlation] = { state: instance[:state], memory: Runtime::Value.materialize(instance[:memory]) }
+            end
+          end
+        end
+
+        # Every `[domain, aggregate_name]` a `for_each` policy could query, resolved
+        # once from every loaded bluebook's own fanning-out policies. Empty when no
+        # domain declares `for_each`, so the snapshot taken before each dispatch costs
+        # nothing until one does.
+        def fan_out_targets
+          @runtime.registry.bluebooks.each_with_object({}) do |(domain, bluebook), targets|
+            bluebook.policies.select(&:fans_out?).each do |policy|
+              query_domain, aggregate_name, = policy.for_each_route(domain)
+              targets[[query_domain, aggregate_name]] ||= @runtime.registry.bluebook(query_domain)&.aggregate(aggregate_name)
+            end
+          end
+        end
+
+        def fan_out_snapshot
+          @fan_out_targets.each_with_object({}) do |((fdomain, faggregate_name), aggregate), snap|
+            next unless aggregate
+
+            snap[[fdomain, faggregate_name]] =
+              @runtime.registry.repository(fdomain, aggregate).all.to_h { |record| [record.id, record.state.dup] }
+          end
+        end
+      end
+    end
+  end
+end