hecks 3.4.2 → 3.6.0

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

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

@@ -1,8 +1,12 @@
+require_relative "query_rows"
+
 module Hecks
   module Fuzzing
     module Properties
       # Properties that check a query's answer against an independent recomputation.
       module Querying
+        include QueryRows
+
         # Differential oracle: each replayed ask is answered natively and by the reference
         # interpreter, and the two must agree.
         #
@@ -13,27 +17,32 @@ module Hecks
         # @param history [Hash] a replayed history as returned by `Replay.call`
         # @return [true, String] true, or a message naming each disagreeing query
         def query_answers_match_reference(history)
-          offenders = history.fetch(:queries).filter_map do |asked|
-            next unless asked[:query].is_a?(String) && asked[:query].include?("::")
+          offenders = history.fetch(:queries).filter_map { |asked| reference_offense(asked) }
+          offenders.empty? || offenders.join("; ")
+        end
 
-            native_refused    = asked.key?(:error)
-            reference_refused = asked.key?(:reference_error)
+        # Whether a replayed ask names an aggregate query (`Domain::Aggregate.Query`) rather than
+        # a read model.
+        def namespaced_query?(asked) = asked[:query].is_a?(String) && asked[:query].include?("::")
 
-            if native_refused != reference_refused
-              next "#{asked[:query]} #{asked[:args].inspect} — native " \
-                   "#{native_refused ? "refused (#{asked[:error]})" : 'answered'}, " \
-                   "but the reference interpreter #{reference_refused ? "refused (#{asked[:reference_error]})" : 'answered'} — " \
-                   "a refusal-shaped divergence, not just a differing row set"
-            end
+        # The message for one ask whose native and reference answers disagree, or nil.
+        def reference_offense(asked)
+          return unless namespaced_query?(asked)
 
-            next if native_refused
-            next if asked[:rows] == asked[:reference_rows]
+          native_refused    = asked.key?(:error)
+          reference_refused = asked.key?(:reference_error)
+          return refusal_divergence(asked, native_refused, reference_refused) if native_refused != reference_refused
+          return if native_refused || asked[:rows] == asked[:reference_rows]
 
-            "#{asked[:query]} #{asked[:args].inspect} answered #{asked[:rows].inspect} " \
-              "natively but #{asked[:reference_rows].inspect} through the reference interpreter"
-          end
+          "#{asked[:query]} #{asked[:args].inspect} answered #{asked[:rows].inspect} " \
+            "natively but #{asked[:reference_rows].inspect} through the reference interpreter"
+        end
 
-          offenders.empty? || offenders.join("; ")
+        def refusal_divergence(asked, native_refused, reference_refused)
+          "#{asked[:query]} #{asked[:args].inspect} — native " \
+            "#{native_refused ? "refused (#{asked[:error]})" : "answered"}, " \
+            "but the reference interpreter #{reference_refused ? "refused (#{asked[:reference_error]})" : "answered"} — " \
+            "a refusal-shaped divergence, not just a differing row set"
         end
 
         # Recomputes order/offset/limit from `history[:instances]` and compares it with the
@@ -43,39 +52,60 @@ module Hecks
         # interpreter; only the offset-then-limit slice is restated. Comparing the interpreter's
         # native and reference paths instead could share one bug.
         #
-        # Kept as one method: the steps run once, in order, and share every intermediate.
-        # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-        #
         # @param history [Hash] a replayed history as returned by `Replay.call`
         # @return [true, String] true, or a message naming each mismatching query
         def paging_offset_partitions_correctly(history)
           bluebooks = history.fetch(:bluebooks)
+          offenders = history.fetch(:queries).filter_map { |asked| paging_offense(bluebooks, asked) }
+          offenders.empty? || offenders.join("; ")
+        end
 
-          offenders = history.fetch(:queries).filter_map do |asked|
-            next if asked[:error] || !asked[:query].is_a?(String) || !asked[:query].include?("::")
+        # The message for one paged ask whose answer differs from the recomputed page, or nil.
+        def paging_offense(bluebooks, asked)
+          declared = paged_query(bluebooks, asked)
+          return unless declared
 
-            declared = query_for_verb(bluebooks, asked[:query])
-            next unless declared&.order_by && (declared.offset || declared.limit)
+          args = normalized_args(bluebooks, asked, declared)
+          rows = eligible_rows_for(bluebooks, asked, declared, args)
+          expected = expected_page(rows, declared, args)
+          return if asked[:rows] == expected
 
-            domain, aggregate_name, = Naming.split_verb(asked[:query])
-            aggregate = bluebooks[domain]&.aggregate(aggregate_name)
-            args = normalize_query_args(aggregate, declared, asked[:args] || {})
-            rows = query_eligible_rows(asked.fetch(:instances_at), domain, aggregate_name, declared.wheres, args,
-                                       bluebooks: bluebooks)
-            ordered = Ports::Query::Ordering.apply(
-              rows, declared.order_by, declared.null_semantics, identity: ->(row) { row[:id].to_s }
-            ) { |row| Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, declared.order_by.field)) }
+          "#{asked[:query]} #{args.inspect} answered #{asked[:rows].inspect}, but independently recomputing " \
+            "order/offset/limit from #{rows.length} eligible row(s) gives #{expected.inspect}"
+        end
 
-            skipped  = declared.offset ? ordered.drop(resolve_paging_value(declared.offset.value, args).to_i) : ordered
-            expected = declared.limit ? skipped.first(resolve_paging_value(declared.limit.value, args).to_i) : skipped
-            actual   = asked[:rows]
-            next if actual == expected
+        # The declared query of an answered ask that pages (`order_by` with offset or limit).
+        def paged_query(bluebooks, asked)
+          return if asked[:error] || !namespaced_query?(asked)
 
-            "#{asked[:query]} #{args.inspect} answered #{actual.inspect}, but independently recomputing " \
-              "order/offset/limit from #{rows.length} eligible row(s) gives #{expected.inspect}"
-          end
+          declared = query_for_verb(bluebooks, asked[:query])
+          declared if declared&.order_by && (declared.offset || declared.limit)
+        end
 
-          offenders.empty? || offenders.join("; ")
+        # The stored rows the asked query's `wheres` admit, in the snapshot the ask ran against.
+        def eligible_rows_for(bluebooks, asked, declared, args)
+          domain, aggregate_name, = Naming.split_verb(asked[:query])
+          snapshot = Snapshot.new(asked.fetch(:instances_at), domain, bluebooks)
+          query_eligible_rows(snapshot, aggregate_name, declared.wheres, args)
+        end
+
+        def normalized_args(bluebooks, asked, declared)
+          domain, aggregate_name, = Naming.split_verb(asked[:query])
+          aggregate = bluebooks[domain]&.aggregate(aggregate_name)
+          normalize_query_args(aggregate, declared, asked[:args] || {})
+        end
+
+        # The rows `declared` should answer: ordered, then offset, then limited.
+        def expected_page(rows, declared, args)
+          ordered = ordered_rows(rows, declared)
+          skipped = declared.offset ? ordered.drop(resolve_paging_value(declared.offset.value, args).to_i) : ordered
+          declared.limit ? skipped.first(resolve_paging_value(declared.limit.value, args).to_i) : skipped
+        end
+
+        def ordered_rows(rows, declared)
+          Ports::Query::Ordering.apply(
+            rows, declared.order_by, declared.null_semantics, identity: ->(row) { row[:id].to_s }
+          ) { |row| Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, declared.order_by.field)) }
         end
 
         # Real dispatch normalizes a query's own declared arguments
@@ -114,57 +144,6 @@ module Hecks
           aggregate&.query(query_path)
         end
 
-        # 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. `bluebooks:` is needed only to resolve a `/` hop clause, whose head
-        # names a declared reference; without it the clause would be dug as a local path.
-        #
-        # @param instances [Hash{String => Hash}] `history[:instances]` or an `:instances_at`
-        #   snapshot
-        # @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(instances, domain, aggregate_name, wheres, args, bluebooks: {})
-          aggregate = bluebooks[domain]&.aggregate(aggregate_name)
-          prefix = "#{domain}::#{aggregate_name}#"
-          instances.filter_map do |key, state|
-            next unless key.start_with?(prefix)
-
-            row = state.merge(id: key.split("#").last)
-            next unless wheres.all? do |clause|
-              resolved = resolve_hop_clause(instances, domain, aggregate, clause, args, bluebooks)
-              held = Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, resolved.field))
-              Ports::Query::InMemory.holds?(resolved, held, args)
-            end
-
-            row
-          end
-        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(instances, domain, aggregate, clause, args, bluebooks)
-          return clause unless aggregate && QuerySpecification::HopPath.hop_head?(clause.field, aggregate.attributes)
-
-          hop, rest = QuerySpecification::HopPath.next_hop(clause.field, aggregate.attributes)
-          target = hop.target
-          return clause unless target
-
-          inner = QuerySpecification::Common::WhereClause.new(field: rest, op: clause.op, value: clause.value)
-          ids   = query_eligible_rows(instances, domain, target.hecks_name, [inner], args, bluebooks: bluebooks)
-                  .map { |row| row[:id].to_s }.uniq
-
-          QuerySpecification::Common::WhereClause.new(field: hop.attribute.name, op: "in", value: ids)
-        end
-
         # Resolves a declared limit/offset: a literal, or a Symbol naming a call arg.
         def resolve_paging_value(value, args)
           value.is_a?(Symbol) ? args[value] : value

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

@@ -0,0 +1,100 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Reads one aggregate's referencing commands against the events of a history.
+      #
+      # An event name that a creating command of the same aggregate also emits is skipped: the
+      # name alone cannot say which command produced it. An identity the payload does not carry
+      # as a plain scalar is inconclusive, not a violation.
+      class ReferenceReading
+        def initialize(domain, bluebook, aggregate, events)
+          @domain = domain
+          @bluebook = bluebook
+          @aggregate = aggregate
+          @events = events
+          @own = "#{domain}::#{aggregate.hecks_name}"
+        end
+
+        # Messages for the emissions of referencing commands that address no earlier record.
+        def dangling
+          referencing.flat_map { |command| command_dangling(command) }
+        end
+
+        private
+
+        def referencing = @aggregate.commands.reject { |command| command.references.to_s.empty? }
+
+        def creating_events
+          creating = @aggregate.commands.select { |command| command.references.to_s.empty? }
+          creating.flat_map { |command| command.emits.map(&:to_s) }
+        end
+
+        def command_dangling(command)
+          key = target_key(command)
+          return [] unless key
+
+          names = command.emits.map(&:to_s) - creating_events
+          @events.each_with_index.filter_map do |event, index|
+            next unless names.include?(event[:name]) && event[:aggregate] == @own
+
+            message(command, event, @events.first(index), key)
+          end
+        end
+
+        def message(command, event, preceding, key)
+          id = referenced_id(event, key)
+          return if id.nil? || preceding.any? { |earlier| earlier[:aggregate] == key && earlier[:id].to_s == id }
+
+          "#{command.hecks_name} (#{@own}##{event[:id]}) was accepted referencing #{key}##{id}, " \
+            "but no earlier event created that record"
+        end
+
+        # The `"Domain::Aggregate"` key the reference points at; nil when the target is not an
+        # aggregate of this domain (a cross-domain reference this property cannot read).
+        def target_key(command)
+          target = Naming.demodulise(command.references)
+          return @own if @own.split("::").last == target
+
+          "#{@domain}::#{target}" if @bluebook.aggregates.any? { |candidate| candidate.hecks_name == target }
+        end
+
+        # The id the emission addressed: the event's own id when the command references its own
+        # aggregate, else the reference key's scalar in the payload. nil when not a plain scalar.
+        def referenced_id(event, key)
+          return event[:id].to_s if key == @own
+
+          value = read(Hash(event[:payload]), Naming.reference_key(key.split("::").last))
+          value = read(value, :value) if value.is_a?(Hash)
+          value.to_s if value.is_a?(String) || value.is_a?(Numeric)
+        end
+
+        # A payload spells its keys as strings or symbols; neither is preferred.
+        def read(hash, name)
+          hash.fetch(name.to_sym) { hash[name.to_s] }
+        end
+      end
+
+      # Property: a command that `references` an aggregate was never accepted against a record
+      # nothing in the history created.
+      #
+      # The dispatch pipeline refuses such a command with NotFound; this reads the accepted
+      # ones back, so a dangling reference that got through shows up as an emission with no
+      # earlier event for the record it addressed. A replay boots empty, so every record that
+      # exists was created by an earlier emission.
+      module References
+        # Every event a referencing command emitted has an earlier event for the referenced record.
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true, or a message naming each emission with a dangling reference
+        def references_resolve_to_earlier_records(history)
+          events = Array(history[:events])
+
+          violations = (history[:bluebooks] || {}).flat_map do |domain, bluebook|
+            bluebook.aggregates.flat_map { |aggregate| ReferenceReading.new(domain, bluebook, aggregate, events).dangling }
+          end
+          violations.empty? || violations.uniq.join("; ")
+        end
+      end
+    end
+  end
+end