hecks 3.5.0 → 3.7.0

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/read_model_names.rb

@@ -0,0 +1,50 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Property: how each declared read model is addressed.
+      module ReadModelNames
+        # Every read model resolves from either spelling of its name, to itself, and no two read
+        # models of one chapter share a `query_name`.
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true, or a message naming each read model that drifts
+        def read_model_names_resolve_uniquely(history)
+          offenders = (history[:bluebooks] || {}).each_value.flat_map { |bluebook| name_offenders(bluebook) }
+          offenders.empty? || offenders.join("; ")
+        end
+
+        def name_offenders(bluebook)
+          models = bluebook.read_models
+          models.flat_map { |model| model_name_offenders(bluebook, model) } + shared_query_names(bluebook, models)
+        end
+
+        def model_name_offenders(bluebook, model)
+          [drifted_name(model), unresolved_name(bluebook, model)].compact
+        end
+
+        def drifted_name(model)
+          return if model.query_name == snake_of(model.name)
+
+          "#{model.name}'s query_name is #{model.query_name.inspect}, not #{snake_of(model.name).inspect}"
+        end
+
+        def unresolved_name(bluebook, model)
+          return if [model.name, model.query_name].all? { |spelling| bluebook.read_model(spelling).equal?(model) }
+
+          "#{model.name} does not resolve to itself by name or by query_name"
+        end
+
+        def shared_query_names(bluebook, models)
+          models.group_by(&:query_name).select { |_name, held| held.size > 1 }.map do |name, held|
+            "#{bluebook.name} declares #{held.map(&:name).join(" and ")} under one query name #{name.inspect}"
+          end
+        end
+
+        # Written out here rather than called, so a drift in `Naming.snake` is a finding.
+        def snake_of(text)
+          text.to_s.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,138 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Property: what a read-model ask composes from its references.
+      #
+      # Leans on `AggregationRecompute`'s own field-reading and foreign-key helpers, which
+      # `InvariantsAndAggregation` already extends into `Properties`.
+      module ReadModels
+        # Every composed read-model ask answered the heads its references name.
+        #
+        # Each head's rows are recomputed from the instances as the ask saw them: the root is the
+        # record the reference names, a many-side head holds the records whose foreign key points at
+        # it, and a rootless model reads every record. A model's filtering options apply only to the
+        # heads they target. A head with no direct foreign key to the root is inconclusive, and a
+        # model that groups, reduces or scopes by tenant is checked by its own properties.
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true, or a message naming each head that composed otherwise
+        def read_model_heads_compose_from_references(history)
+          bluebooks = history.fetch(:bluebooks, {})
+          offenders = Array(history[:queries]).flat_map { |ask| composition_offenders(ask, bluebooks) }
+          offenders.empty? || offenders.uniq.join("; ")
+        end
+
+        def composition_offenders(ask, bluebooks)
+          bluebook, model = composed_read_model(ask, bluebooks)
+          return [] unless model
+
+          answer = ask[:rows].first || {}
+          offenders = model.aggregate_heads.filter_map { |head| head_offender(bluebook, model, head, ask) }
+          offenders + unexpected_heads(ask[:query], model, answer)
+        end
+
+        # The `[bluebook, read_model]` a successful bare-domain ask named; nil when out of scope.
+        def composed_read_model(ask, bluebooks)
+          return unless answered_read_model_ask?(ask)
+
+          domain, name = ask[:query].split(".", 2)
+          bluebook = bluebooks[domain]
+          model = bluebook&.read_model(name)
+          [bluebook, model] if model && composable?(model)
+        end
+
+        # A bare-domain ask (no `::`, so a read model, not an aggregate query) that was answered.
+        def answered_read_model_ask?(ask)
+          query = ask[:query]
+          query.is_a?(String) && !query.include?("::") && !ask[:error] && ask[:rows].is_a?(Array)
+        end
+
+        def composable?(model)
+          !model.reducing? && model.group_by.empty? && !model.authorization&.tenant
+        end
+
+        def unexpected_heads(query, model, answer)
+          declared = model.aggregate_heads.map { |head| head[:as] }.sort
+          return [] if answer.keys.sort == declared
+
+          ["#{query} answered heads #{answer.keys.sort.inspect}, but declares #{declared.inspect}"]
+        end
+
+        def head_offender(bluebook, model, head, ask)
+          expected = expected_head_states(bluebook, model, head, ask)
+          return unless expected
+
+          answered = answered_ids(head, (ask[:rows].first || {})[head[:as]])
+          problem = head_problem(model, head, expected, [answered, ask[:args]])
+          "#{ask[:query]} head #{head[:as]}: #{problem}" if problem
+        end
+
+        def answered_ids(head, answer)
+          rows = head[:many] ? answer.to_a : [answer].compact
+          rows.map { |row| row[:id].to_s }
+        end
+
+        # The states a head should hold before any option applies, sorted by id; nil when the head
+        # has no direct foreign key to the root, which this property cannot read.
+        def expected_head_states(bluebook, model, head, ask)
+          prefix = "#{bluebook.name}::#{head[:aggregate]}#"
+          states = ask[:instances_at].filter_map { |key, state| state.merge(id: key.split("#").last) if key.start_with?(prefix) }
+          held = candidate_states(bluebook, model, head, states, ask[:args])
+          held&.sort_by { |state| state[:id].to_s }
+        end
+
+        def candidate_states(bluebook, model, head, states, args)
+          return states if model.reference_target.nil?
+
+          reference_id = args[model.reference_name].to_s
+          return states.select { |state| state[:id].to_s == reference_id } if head[:aggregate] == model.reference_target
+
+          referencing_states(bluebook, model, head, states, reference_id)
+        end
+
+        # The states whose foreign key holds the reference; nil when the head has no such key.
+        def referencing_states(bluebook, model, head, states, reference_id)
+          aggregate = bluebook.aggregate(head[:aggregate])
+          fields = aggregate ? foreign_key_fields(aggregate, model) : []
+          states.select { |state| fields.any? { |field| state[field].to_s == reference_id } } unless fields.empty?
+        end
+
+        # `asked` is the answered ids and the ask's arguments, which a `where` value may read.
+        def head_problem(model, head, expected, asked)
+          answered, args = asked
+          return exact_problem(expected, answered) unless model.filtered_head_names.include?(head[:as])
+
+          scoped_problem(model.options_for(head[:as]), expected, answered, args)
+        end
+
+        # An untargeted head holds exactly the states the references name, in any order.
+        def exact_problem(expected, answered)
+          ids = expected.map { |state| state[:id].to_s }
+          return if answered.sort == ids.sort
+
+          "answered #{answered.inspect}, but the references compose #{ids.inspect}"
+        end
+
+        # A targeted head holds the states its `where` clauses admit; `order_by` only reorders them
+        # and a `limit` or `offset` can only narrow them.
+        def scoped_problem(options, expected, answered, args)
+          kept = expected.select { |state| options.wheres.all? { |clause| head_clause_holds?(clause, state, args) } }
+          return exact_problem(kept, answered) unless options.limit || options.offset
+
+          narrowed_problem(kept.map { |state| state[:id].to_s }, answered)
+        end
+
+        def narrowed_problem(admitted, answered)
+          return if (answered - admitted).empty? && answered.size <= admitted.size
+
+          "answered #{answered.inspect}, beyond what its where clauses admit #{admitted.inspect}"
+        end
+
+        # Named for heads: `query_rows.rb` already owns `clause_holds?` in this namespace.
+        def head_clause_holds?(clause, state, args)
+          Ports::Query::InMemory.holds?(clause, comparable_field(state, clause.field), args)
+        end
+      end
+    end
+  end
+end

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

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

@@ -0,0 +1,50 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Property: the role check at dispatch agrees with the grants the replay itself made.
+      #
+      # `CommandRules::Authorization` asks the authorization provider whether an identified caller
+      # holds a command's role, through the `assignments` verb the provider's chapter declares with
+      # `provides "authorization"`. Each `history[:role_checks]` entry carries the grants read back
+      # through that same verb before the dispatch, so the answer is recomputed from them.
+      module RoleChecks
+        # How `Replay.refusal_kind` names the refusal the role gate raises.
+        UNAUTHORIZED = "Hecks::Runtime::Unauthorized".freeze
+
+        # An identified caller holding a live grant of the role is never refused as unauthorized,
+        # and one holding none is never accepted.
+        #
+        # A refusal other than Unauthorized proves nothing about the grant: argument gates run
+        # before the role gate, so an ungranted caller can be turned away for another reason first.
+        #
+        # @param history [Hash] a replayed history, as returned by `Fuzzing::Replay.call`
+        # @return [true, String] true, or a message naming each dispatch the grants contradict
+        def role_checks_agree_with_grants(history)
+          offenders = Array(history[:role_checks]).filter_map { |check| role_check_offender(check) }
+          offenders.empty? || offenders.uniq.join("; ")
+        end
+
+        # A message when `check`'s outcome contradicts its grants; nil when consistent or unclear.
+        def role_check_offender(check)
+          held = role_held?(check)
+          return refused_message(check) if held && check[:outcome] == UNAUTHORIZED
+
+          accepted_message(check) if !held && check[:outcome].nil?
+        end
+
+        def role_held?(check)
+          check[:grants].any? { |grant| grant[:role] == check[:role] && !grant[:ended] }
+        end
+
+        def refused_message(check)
+          "#{check[:verb]} was refused as unauthorized for #{check[:actor_id]}, who holds a live grant of " \
+            "#{check[:role].inspect}"
+        end
+
+        def accepted_message(check)
+          "#{check[:verb]} was accepted for #{check[:actor_id]}, who holds no live grant of #{check[:role].inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Tenant-scoping property over a replayed history: no stored record references a record
+      # carrying a different tenant value.
+      module TenantScope
+        # One stored record under inspection: where it lives, its state, and its own tenant.
+        Record = Struct.new(:bluebooks, :instances, :key, :domain_name, :state, :field, :tenant) do
+          # The aggregate called `name` in the record's own domain, or nil.
+          def aggregate_named(name) = bluebooks[domain_name]&.aggregate(name)
+
+          # The key of the stored record `id` of `target` in the record's own domain.
+          def target_key(target, id) = "#{domain_name}::#{target.name}##{id}"
+        end
+
+        # Checks that no stored record references a record carrying a different tenant value.
+        #
+        # Commands cannot declare `authorize`, so nothing refuses a cross-tenant write.
+        # Tenants compare via Query::InMemory.comparable: value objects with different
+        # declared names are unequal under Value#== even for the same tenant.
+        def commands_respect_tenant_scope(history)
+          bluebooks = history.fetch(:bluebooks)
+          instances = history.fetch(:instances)
+          offenders = instances.flat_map { |key, state| tenant_offenders(bluebooks, instances, key, state) }
+          offenders.empty? || offenders.join("; ")
+        end
+
+        # One message per reference of the stored record `key` that crosses a tenant.
+        def tenant_offenders(bluebooks, instances, key, state)
+          domain_name = key.split("::").first
+          aggregate = aggregate_for_key(bluebooks, key)
+          return [] unless aggregate
+
+          field = tenant_field_for(aggregate)
+          return [] unless field && state.key?(field)
+
+          record = Record.new(bluebooks, instances, key, domain_name, state, field,
+                              Ports::Query::InMemory.comparable(state[field]))
+          aggregate.attributes.filter_map { |attribute| cross_tenant_offense(record, attribute) }
+        end
+
+        # The aggregate a stored-record key `Domain::Aggregate#id` belongs to, or nil.
+        def aggregate_for_key(bluebooks, key)
+          bluebooks[key.split("::").first]&.aggregate(key.split("::").last.split("#").first)
+        end
+
+        # The message for one reference whose target carries a different tenant, or nil.
+        def cross_tenant_offense(record, attribute)
+          return unless attribute.type.is_a?(Bluebook::Reference)
+
+          target = record.aggregate_named(attribute.type.target_name)
+          target_id = record.state[attribute.name]
+          return unless target && target_id
+
+          target_field, target_tenant = referenced_tenant(record, target, target_id)
+          return if target_field.nil? || target_tenant == record.tenant
+
+          cross_tenant_message(record, "#{attribute.name}: #{target_id.inspect}",
+                               record.target_key(target, target_id), target_field, target_tenant)
+        end
+
+        def cross_tenant_message(record, reference, target_key, target_field, target_tenant)
+          "#{record.key} (#{record.field}: #{record.tenant.inspect}) references #{reference}, " \
+            "but #{target_key} carries #{target_field}: #{target_tenant.inspect} — a cross-tenant write nothing refused"
+        end
+
+        # The tenant field and value of the stored record `target_id` names, or nil.
+        def referenced_tenant(record, target, target_id)
+          target_field = tenant_field_for(target)
+          target_state = record.instances[record.target_key(target, target_id)]
+          return unless target_field && target_state&.key?(target_field)
+
+          [target_field, Ports::Query::InMemory.comparable(target_state[target_field])]
+        end
+
+        # The field named by `authorize ..., tenant:` on any of the aggregate's queries, or nil.
+        def tenant_field_for(aggregate)
+          authorization = aggregate.queries.filter_map(&:authorization).find(&:tenant)
+          authorization&.tenant&.to_sym
+        end
+      end
+    end
+  end
+end