hecks 3.5.0 → 3.7.0

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

@@ -13,49 +13,60 @@ module Hecks
         # @return [true, String] true, or a message naming each offending instance
         def lifecycle_values_are_declared(history)
           bluebook = history.fetch(:bluebook)
-          declared = {}
-          bluebook.aggregates.each do |aggregate|
-            declared[aggregate.hecks_name] = Bluebook::ModelCheck.full_states(aggregate.lifecycle) if aggregate.lifecycle
+          declared = bluebook.aggregates.select(&:lifecycle).to_h do |aggregate|
+            [aggregate.hecks_name, Bluebook::ModelCheck.full_states(aggregate.lifecycle)]
           end
           return true if declared.empty?
 
           offenders = history.fetch(:instances).filter_map do |key, state|
-            aggregate_name = key.split("::").last.split("#").first
-            states = declared[aggregate_name]
-            next unless states
-
-            lifecycle = bluebook.aggregate(aggregate_name).lifecycle
-            value = state[lifecycle.field]
-            next if value.nil? || states.include?(value.to_s)
-
-            "#{key} holds #{lifecycle.field}=#{value.inspect}, which #{aggregate_name} never declares as a state"
+            undeclared_state_offense(bluebook, declared, key, state)
           end
 
           offenders.empty? || offenders.join("; ")
         end
 
+        # The message for one stored record holding an undeclared lifecycle state, or nil.
+        def undeclared_state_offense(bluebook, declared, key, state)
+          aggregate_name = key.split("::").last.split("#").first
+          states = declared[aggregate_name]
+          return unless states
+
+          lifecycle = bluebook.aggregate(aggregate_name).lifecycle
+          value = state[lifecycle.field]
+          return if value.nil? || states.include?(value.to_s)
+
+          "#{key} holds #{lifecycle.field}=#{value.inspect}, which #{aggregate_name} never declares as a state"
+        end
+
         # Every logged saga advance follows a `(from_state, to_state)` pair some handler declares.
         #
         # @param history [Hash] a replayed history as returned by `Replay.call`
         # @return [true, String] true, or a message naming the process manager and undeclared pair
         def saga_advances_follow_declared_handlers(history)
-          bluebook = history.fetch(:bluebook)
+          edges = saga_edges(history.fetch(:bluebook))
+          return true if edges.empty?
+
+          offenders = history.fetch(:sagas).filter_map { |entry| saga_advance_offense(edges, entry) }
+          offenders.empty? || offenders.join("; ")
+        end
+
+        # The `(from_state, to_state)` pairs each process manager's handlers declare.
+        def saga_edges(bluebook)
           edges = Hash.new { |h, k| h[k] = [] }
           bluebook.process_managers.each do |pm|
             pm.handlers.each { |handler| edges[pm.name] << [handler.from_state, handler.to_state] }
           end
-          return true if edges.empty?
-
-          offenders = history.fetch(:sagas).filter_map do |entry|
-            next unless entry[:advanced]
+          edges
+        end
 
-            pair = [entry[:from], entry[:to]]
-            next if edges[entry[:process_manager]].include?(pair)
+        # The message for one logged saga advance no handler declares, or nil.
+        def saga_advance_offense(edges, entry)
+          return unless entry[:advanced]
 
-            "#{entry[:process_manager]} advanced #{pair.inspect}, which no declared handler names"
-          end
+          pair = [entry[:from], entry[:to]]
+          return if edges[entry[:process_manager]].include?(pair)
 
-          offenders.empty? || offenders.join("; ")
+          "#{entry[:process_manager]} advanced #{pair.inspect}, which no declared handler names"
         end
 
         # Replaying the same steps on a fresh boot yields identical events, refusals and instances.
@@ -70,22 +81,22 @@ module Hecks
         def replay_is_deterministic(domain_path, steps, adapter: :memory)
           first  = Replay.call(domain_path, steps, adapter: adapter)
           second = Replay.call(domain_path, steps, adapter: adapter)
+          return true if comparable_history(first) == comparable_history(second)
 
-          # What is stripped is declared in `Nondeterministic::FIELDS`. Outbox rows are stripped
-          # per row, not dropped, so status, consumer and event payload stay checked.
-          strip_outbox_nondeterminism = lambda do |history|
-            traces = Array(history[:outbox_traces]).map do |trace|
-              trace.merge(rows: trace[:rows].map do |row|
-                Nondeterministic.strip(row, :outbox_row).merge(event: Nondeterministic.strip(row[:event], :event))
-              end)
-            end
-            history.merge(outbox_traces: traces)
-          end
+          "two replays of the same #{steps.length} steps produced different histories"
+        end
 
-          comparable = ->(history) { Nondeterministic.strip(strip_outbox_nondeterminism.call(history), :history) }
-          return true if comparable.call(first) == comparable.call(second)
+        # What is stripped is declared in `Nondeterministic::FIELDS`. Outbox rows are stripped
+        # per row, not dropped, so status, consumer and event payload stay checked.
+        def comparable_history(history)
+          traces = Array(history[:outbox_traces]).map do |trace|
+            trace.merge(rows: trace[:rows].map { |row| stripped_outbox_row(row) })
+          end
+          Nondeterministic.strip(history.merge(outbox_traces: traces), :history)
+        end
 
-          "two replays of the same #{steps.length} steps produced different histories"
+        def stripped_outbox_row(row)
+          Nondeterministic.strip(row, :outbox_row).merge(event: Nondeterministic.strip(row[:event], :event))
         end
       end
     end

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

@@ -0,0 +1,162 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Independent recomputations of what each mutation op leaves behind, for
+      # `DispatchAndMutations#mutations_match_recompute` to compare against the real dispatch.
+      module MutationRecompute
+        # What a recomputation needs of the step it re-derives.
+        #
+        # `before` is the entity's state before the dispatch; `owner` is the construct declaring
+        # the mutated attribute, the root aggregate unless a dot-shaped command names an entity.
+        Context = Struct.new(:aggregate, :command, :owner, :before, :args)
+
+        # Dispatches to the recompute rule for `mutation.op`.
+        #
+        # @param mutation [Object] the mutation the command declares
+        # @param current [Object] the mutated attribute's value before the dispatch
+        # @param context [Context] the step being re-derived
+        # @return [Object, Symbol] the recomputed after-value, or `:unrecomputable`
+        def recompute_mutation(mutation, current, context)
+          case mutation.op
+          when :append   then recompute_append(current, mutation.source, context, mutation.target)
+          when :remove   then recompute_remove(current, mutation.source, context.args)
+          when :multiply then recompute_multiply(current, resolve_mutation_source(mutation.source, context.args))
+          when :clamp    then recompute_clamp(current, mutation.source)
+          when :set      then recompute_set(mutation.source, context, 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, context, target)
+          raw = resolve_mutation_source(source, context.args)
+          attribute = context.owner&.attribute(target)
+          coerced = attribute ? Runtime::Value.for_attribute(context.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, context, target = nil)
+          fields = source_map.transform_values { |source| resolve_mutation_append_field(source, context) }
+          fill_recompute_declared_defaults(context, 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(context, target, fields)
+          element_type = target && context.owner&.attribute(target)&.type
+          return fields unless element_type
+
+          entity = context.owner.entities.find { |piece| piece.hecks_name == element_type.to_s }
+          return fill_entity_defaults(context.aggregate, entity, fields) if entity
+
+          fill_value_object_defaults(context.aggregate, element_type, fields)
+        end
+
+        def fill_entity_defaults(aggregate, entity, fields)
+          entity.attributes.each do |attribute|
+            next if fields.key?(attribute.name)
+
+            fields[attribute.name] = attribute.list? ? [] : Runtime::Instance.default_for(aggregate, attribute)
+          end
+          fields
+        end
+
+        def fill_value_object_defaults(aggregate, element_type, fields)
+          value_object = aggregate.value_object(element_type)
+          value_object ? Runtime::Value.apply_defaults(value_object, fields) : fields
+        end
+
+        # Resolves one appended field's value from its declared source.
+        def resolve_mutation_append_field(source, context)
+          return source unless source.is_a?(Symbol)
+          return context.before[source] unless context.args.key?(source)
+
+          coerce_recompute_append_arg(context, source, context.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(context, source, raw)
+          attribute = context.command.attribute(source)
+          return raw unless attribute
+
+          Runtime::Value.materialize(Runtime::Value.for_attribute(context.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)
+
+          apply_to_number(current) { |number| number * amount }
+        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
+          apply_to_number(current) { |number| number.clamp(min, max) }
+        end
+
+        # Yields a bare Numeric, or the first numeric field of a Hash, and puts the result back.
+        # Anything else, or a Hash with no numeric field, is `:unrecomputable`; nil counts as 0.
+        def apply_to_number(current)
+          current ||= 0
+          return yield(current) if current.is_a?(Numeric)
+          return :unrecomputable unless current.is_a?(Hash)
+
+          field = current.keys.find { |f| current[f].is_a?(Numeric) }
+          return :unrecomputable unless field
+
+          current.merge(field => yield(current[field]))
+        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

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

@@ -28,20 +28,24 @@ module Hecks
           on = row.dig(:event, :name)
 
           case row[:status]
-          when "pending", "claimed"
-            ["outbox row #{row[:delivery_id]} (#{row[:consumer]} on #{on}) never drained inline — status stayed " \
-             "#{row[:status].inspect} though delivery is inline by contract (Runtime::Outbox's own header)"]
-          when "failed"
-            ["outbox row #{row[:delivery_id]} (#{row[:consumer]} on #{on}) failed to deliver: #{row[:error]} — " \
-             "a domain refusal never reaches this far; a failed row names a defect in the relay's own consumer " \
-             "resolution"]
-          when "delivered"
-            outbox_delivered_policy_offenders(row, on, trace, bluebooks)
-          else
-            []
+          when "pending", "claimed" then [undrained_message(row, on)]
+          when "failed"             then [failed_message(row, on)]
+          when "delivered"          then outbox_delivered_policy_offenders(row, on, trace, bluebooks)
+          else []
           end
         end
 
+        def undrained_message(row, on)
+          "outbox row #{row[:delivery_id]} (#{row[:consumer]} on #{on}) never drained inline — status stayed " \
+            "#{row[:status].inspect} though delivery is inline by contract (Runtime::Outbox's own header)"
+        end
+
+        def failed_message(row, on)
+          "outbox row #{row[:delivery_id]} (#{row[:consumer]} on #{on}) failed to deliver: #{row[:error]} — " \
+            "a domain refusal never reaches this far; a failed row names a defect in the relay's own consumer " \
+            "resolution"
+        end
+
         # Offending messages for a delivered `policy:` row that has no `reaction_log` entry.
         #
         # Legitimate only when the policy's `where` does not hold; a saga row gets no such check.
@@ -50,21 +54,34 @@ module Hecks
           return [] unless kind == "policy"
 
           home, name = fqn.to_s.split("::", 2)
-          return [] if trace[:reactions].any? { |entry| entry[:policy] == name && entry[:on] == on }
+          return [] if reacted?(trace, name, on)
 
           policy = bluebooks[home]&.policies&.find { |candidate| candidate.name == name }
-          # Undeclared policy: inconclusive, not a mismatch.
-          return [] unless policy
-          # Fan-out counts belong to fanout_dispatches_once_per_matching_row.
-          return [] if policy.fans_out?
-
-          held = independently_re_evaluate_policy_where(policy, row[:event])
-          # False or inconclusive (the where raised): never a mismatch.
-          return [] if held != true
-
-          ["outbox row #{row[:delivery_id]} (#{row[:consumer]} on #{on}) drained as delivered, but no matching " \
-           "reaction_log entry exists and the policy's own where clause independently re-evaluates true — " \
-           "PolicyInterpreter#deliver only ever returns nil (no reaction_log entry) when where does not hold"]
+          return [] unless dropped_reaction_suspected?(policy, row[:event])
+
+          [dropped_reaction_message(row, on)]
+        end
+
+        def reacted?(trace, policy_name, on)
+          trace[:reactions].any? { |entry| entry[:policy] == policy_name && entry[:on] == on }
+        end
+
+        def dropped_reaction_message(row, on)
+          "outbox row #{row[:delivery_id]} (#{row[:consumer]} on #{on}) drained as delivered, but no matching " \
+            "reaction_log entry exists and the policy's own where clause independently re-evaluates true — " \
+            "PolicyInterpreter#deliver only ever returns nil (no reaction_log entry) when where does not hold"
+        end
+
+        # Whether a delivered policy row with no reaction should have produced one.
+        #
+        # An undeclared policy is inconclusive, not a mismatch; fan-out counts belong to
+        # fanout_dispatches_once_per_matching_row; a `where` that is false, or raised, is never a
+        # mismatch.
+        def dropped_reaction_suspected?(policy, event)
+          return false unless policy
+          return false if policy.fans_out?
+
+          independently_re_evaluate_policy_where(policy, event) == true
         end
 
         # Re-evaluates the policy's `where` against the row's recorded payload.

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

@@ -0,0 +1,61 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Re-checks the invariants of stored records and of the entity elements nested in them,
+      # independently of the call site that was supposed to refuse a violation live.
+      module PieceInvariants
+        # The message for one stored record that violates an invariant, or nil.
+        def stored_record_offense(bluebooks, key, state)
+          domain_name    = key.split("::").first
+          aggregate_name = key.split("::").last.split("#").first
+          aggregate      = bluebooks[domain_name]&.aggregate(aggregate_name)
+          return unless aggregate
+
+          violated = violated_invariant(aggregate, state)
+          return "#{key} violates #{aggregate_name}'s own declared invariant #{violated.description.inspect}" if violated
+
+          check_piece_invariants(aggregate, state, key)
+        end
+
+        # The first invariant of `construct` that `state` does not satisfy, or nil.
+        def violated_invariant(construct, state)
+          construct.invariants.find { |invariant| !Bluebook::Expression::Evaluator.call(invariant.canonical, state) }
+        end
+
+        # A piece's own invariant, checked against every element its owner's
+        # `list_of` field holds — reapplies Admissibility#check_entity_invariants'
+        # own lookup against a plain Hash state rather than a live Instance.
+        def check_piece_invariants(owner_construct, owner_state, key)
+          owner_construct.entities.each do |entity|
+            next if entity.invariants.empty?
+
+            list_attr = list_attribute_for(owner_construct, entity)
+            next unless list_attr
+
+            Array(owner_state[list_attr.name]).each do |element|
+              problem = piece_problem(entity, element, key)
+              return problem if problem
+            end
+          end
+          nil
+        end
+
+        # The owner's `list_of` attribute holding `entity`'s elements.
+        def list_attribute_for(owner_construct, entity)
+          owner_construct.attributes.find { |a| a.list? && a.type.to_s == entity.hecks_name }
+        end
+
+        # The message for one piece element that violates, or whose own nested pieces violate.
+        def piece_problem(entity, element, key)
+          violated = violated_invariant(entity, element)
+          if violated
+            return "#{key}'s own #{entity.hecks_name} violates its declared invariant " \
+                   "#{violated.description.inspect}"
+          end
+
+          check_piece_invariants(entity, element, key)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,140 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Property: every reaction a replay logged is the one its policy declares.
+      #
+      # `PolicyInterpreter` selects policies by `event_name` and builds the trigger from
+      # `target_domain` and `trigger_command`; this reads each logged reaction back against the
+      # declaration, so a policy that fired on an event it never named, or dispatched somewhere
+      # it never declared, is caught.
+      module PolicyWiring
+        # Every `history[:reactions]` entry names a declared policy, was logged for the event
+        # that policy answers (and one that happened), and triggered the declared target.
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true, or a message naming each reaction that disagrees
+        def policy_reactions_follow_declared_wiring(history)
+          bluebooks = history.fetch(:bluebooks, {})
+          events = Array(history[:events])
+
+          offenders = Array(history[:reactions]).filter_map { |reaction| wiring_offender(reaction, bluebooks, events) }
+          offenders.empty? || offenders.uniq.join("; ")
+        end
+
+        # A policy declared `expect_undelivered` is held to its word at runtime: its reaction is
+        # never delivered, and an event it answers is never silently dropped.
+        #
+        # model_check holds the static half (a reachable target makes the declaration stale);
+        # this is the dynamic half, over a replay. A policy with a `where` or a `for_each` may
+        # legitimately log nothing, so the missing-reaction check skips those.
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true, or a message naming each policy that broke its declaration
+        def declared_undelivered_policies_stay_undelivered(history)
+          bluebooks = history.fetch(:bluebooks, {})
+          reactions = Array(history[:reactions])
+          events = Array(history[:events])
+
+          offenders = declared_undelivered(bluebooks).flat_map do |policy, home|
+            delivered_offenders(policy, reactions) + silent_offenders(policy, home, reactions, events)
+          end
+          offenders.empty? || offenders.uniq.join("; ")
+        end
+
+        # Every `[policy, home]` pair across the bluebooks that declares `expect_undelivered`.
+        def declared_undelivered(bluebooks)
+          bluebooks.flat_map do |home, bluebook|
+            bluebook.policies.select(&:expect_undelivered).map { |policy| [policy, home.to_s] }
+          end
+        end
+
+        def delivered_offenders(policy, reactions)
+          delivered = reactions.select { |reaction| reaction[:policy] == policy.name && reaction[:delivered] == true }
+          delivered.map do |reaction|
+            "policy #{policy.name} declares expect_undelivered, but its reaction to #{reaction[:on]} was delivered"
+          end
+        end
+
+        # An event the policy answers, with no reaction logged at all: a silent drop.
+        def silent_offenders(policy, home, reactions, events)
+          return [] if policy.guarded? || policy.fans_out?
+
+          events.select { |event| answers_event?(policy, event) && !reacted_to?(reactions, policy, event) }
+                .map { |event| silent_message(policy, home, event) }
+        end
+
+        def silent_message(policy, home, event)
+          "policy #{policy.name} (#{home}) answers #{event[:name]}, which was emitted, yet logged no reaction"
+        end
+
+        def reacted_to?(reactions, policy, event)
+          reactions.any? { |reaction| reaction[:policy] == policy.name && reaction[:on] == event[:name] }
+        end
+
+        def answers_event?(policy, event)
+          event[:name] == policy.event_name &&
+            (policy.event_qualifier.nil? || event[:aggregate].to_s.split("::").last == policy.event_qualifier)
+        end
+
+        # One message for a reaction no declaration of its policy accounts for; nil when one does.
+        #
+        # A policy name can repeat across domains, so a reaction passes when any declaration
+        # of that name agrees with it on all three of event, trigger and qualifier.
+        def wiring_offender(reaction, bluebooks, events)
+          declared = declared_policies(reaction[:policy], bluebooks)
+          return "reaction names policy #{reaction[:policy]}, which no loaded bluebook declares" if declared.empty?
+
+          wiring_failure(reaction, declared, events)
+        end
+
+        # The first stage of event, trigger and happened-event that no declaration satisfies.
+        def wiring_failure(reaction, declared, events)
+          answering = declared.select { |policy, _home| policy.event_name == reaction[:on].to_s }
+          return unanswered_message(reaction, declared) if answering.empty?
+
+          targeted = answering.select { |policy, home| declared_trigger(policy, home) == reaction[:trigger].to_s }
+          return misrouted_message(reaction, answering) if targeted.empty?
+
+          phantom_failure(reaction, targeted, events)
+        end
+
+        def phantom_failure(reaction, targeted, events)
+          return if targeted.any? { |policy, _home| event_happened?(events, policy, reaction[:on]) }
+
+          phantom_message(reaction)
+        end
+
+        # Every `[policy, home_domain]` pair declared under `name`, across all loaded bluebooks.
+        def declared_policies(name, bluebooks)
+          bluebooks.flat_map do |home, bluebook|
+            bluebook.policies.select { |policy| policy.name == name.to_s }.map { |policy| [policy, home.to_s] }
+          end
+        end
+
+        # The trigger string the runtime builds: the target domain, else the policy's own home.
+        def declared_trigger(policy, home)
+          "#{policy.target_domain || home}::#{policy.trigger_command}"
+        end
+
+        # Whether `events` holds an emission of `name` the policy's event qualifier admits.
+        def event_happened?(events, policy, name)
+          events.any? { |event| event[:name] == name.to_s && answers_event?(policy, event) }
+        end
+
+        def unanswered_message(reaction, declared)
+          named = declared.map { |policy, _home| policy.event_name }.uniq.join(" / ")
+          "policy #{reaction[:policy]} reacted to #{reaction[:on]}, but it declares #{named}"
+        end
+
+        def misrouted_message(reaction, answering)
+          named = answering.map { |policy, home| declared_trigger(policy, home) }.uniq.join(" / ")
+          "policy #{reaction[:policy]} triggered #{reaction[:trigger]} on #{reaction[:on]}, but it declares #{named}"
+        end
+
+        def phantom_message(reaction)
+          "policy #{reaction[:policy]} reacted to #{reaction[:on]}, but no such event was emitted in this history"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Recomputes which stored rows a query's `where` clauses admit, resolving reference hops
+      # over the replay snapshot.
+      module QueryRows
+        # The stored instances a query is recomputed over, with the domain they are read in and
+        # every loaded bluebook (to resolve reference hops).
+        Snapshot = Struct.new(:instances, :domain, :bluebooks)
+
+        # Recomputes which of an aggregate's own stored rows a query's `wheres` admit.
+        #
+        # Rows get `id:` merged in because Ordering.apply's `identity:` and the real answer
+        # both use it. The snapshot's `bluebooks` are needed only to resolve a `/` hop clause.
+        #
+        # @param snapshot [Snapshot] `history[:instances]` or an `:instances_at` snapshot
+        # @param aggregate_name [String] the aggregate whose rows are read
+        # @param wheres [Array<QuerySpecification::Common::WhereClause>] clauses every row
+        #   must satisfy
+        # @param args [Hash] the query's call args, for clauses whose value is a Symbol
+        # @return [Array<Hash>] each admitted row's state, merged with its `id:`
+        def query_eligible_rows(snapshot, aggregate_name, wheres, args)
+          aggregate = snapshot.bluebooks[snapshot.domain]&.aggregate(aggregate_name)
+          prefix = "#{snapshot.domain}::#{aggregate_name}#"
+          snapshot.instances.filter_map do |key, state|
+            next unless key.start_with?(prefix)
+
+            row = state.merge(id: key.split("#").last)
+            row if wheres.all? { |clause| clause_holds?(snapshot, aggregate, clause, args, row) }
+          end
+        end
+
+        # Whether `row` satisfies one clause, after resolving any reference hop in it.
+        def clause_holds?(snapshot, aggregate, clause, args, row)
+          resolved = resolve_hop_clause(snapshot, aggregate, clause, args)
+          held = Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, resolved.field))
+          Ports::Query::InMemory.holds?(resolved, held, args)
+        end
+
+        # Resolves one hop of a `/`-chained clause into a local `in` clause over the target's ids.
+        #
+        # Restates `Runtime::ReferenceHop#fold` over the replay snapshot, so the property never
+        # checks the runtime against its own code path. A clause with no resolvable hop head
+        # is returned unchanged.
+        #
+        # @param aggregate [Bluebook::Aggregate, nil] nil skips hop resolution
+        # @return [QuerySpecification::Common::WhereClause] `clause`, or the `in` clause
+        def resolve_hop_clause(snapshot, aggregate, clause, args)
+          return clause unless aggregate && QuerySpecification::HopPath.hop_head?(clause.field, aggregate.attributes)
+
+          hop, rest = QuerySpecification::HopPath.next_hop(clause.field, aggregate.attributes)
+          return clause unless hop.target
+
+          hop_in_clause(snapshot, hop, rest, clause, args)
+        end
+
+        # The `in` clause over the ids of the hop target's rows that satisfy the rest of the path.
+        def hop_in_clause(snapshot, hop, rest, clause, args)
+          inner = QuerySpecification::Common::WhereClause.new(field: rest, op: clause.op, value: clause.value)
+          ids   = query_eligible_rows(snapshot, hop.target.hecks_name, [inner], args).map { |row| row[:id].to_s }.uniq
+
+          QuerySpecification::Common::WhereClause.new(field: hop.attribute.name, op: "in", value: ids)
+        end
+      end
+    end
+  end
+end