hecks 3.5.0 → 3.6.0

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

@@ -1,3 +1,5 @@
+require_relative "mutation_recompute"
+
 module Hecks
   module Fuzzing
     module Properties
@@ -11,26 +13,36 @@ module Hecks
         # @return [true, String] true if every dry-run trace shows no change; otherwise
         #   a semicolon-joined message naming each offending dry run
         def dry_runs_leave_no_trace(history)
-          offenders = Array(history[:dry_run_traces]).filter_map do |entry|
-            before = entry[:before]
-            after  = entry[:after]
-            next unless before && after
+          offenders = Array(history[:dry_run_traces]).filter_map { |entry| dry_run_offender(entry) }
+          offenders.empty? || offenders.join("; ")
+        end
 
-            traces = []
-            traces << "events #{before[:events]} -> #{after[:events]}" unless before[:events] == after[:events]
-            traces << "instances changed" unless before[:instances] == after[:instances]
-            next if traces.empty?
+        # The message for one dry run that left a trace, or nil.
+        def dry_run_offender(entry)
+          before = entry[:before]
+          after  = entry[:after]
+          return unless before && after
 
-            "dry run of #{entry[:verb]} (ok: #{entry[:ok]}) left a trace: #{traces.join(', ')}"
-          end
+          traces = dry_run_changes(before, after)
+          return if traces.empty?
 
-          offenders.empty? || offenders.join("; ")
+          "dry run of #{entry[:verb]} (ok: #{entry[:ok]}) left a trace: #{traces.join(", ")}"
+        end
+
+        # What differs between a dry run's before and after snapshots.
+        def dry_run_changes(before, after)
+          traces = []
+          traces << "events #{before[:events]} -> #{after[:events]}" unless before[:events] == after[:events]
+          traces << "instances changed" unless before[:instances] == after[:instances]
+          traces
         end
       end
 
       # Properties: saga/policy dispatch args match their `with_spec`, and command
       # mutations match an independent recomputation.
       module DispatchAndMutations
+        include MutationRecompute
+
         # Checks saga and policy dispatch args against an independent re-derivation of
         # `with_spec`. Re-deriving, not calling the interpreter again, keeps the check
         # from agreeing with itself. Args are compared as captured live, because a
@@ -41,7 +53,13 @@ module Hecks
         #   match an independent re-derivation of their `with_spec`; otherwise a
         #   semicolon-joined message naming each offending dispatch
         def dispatch_binding_fidelity(history)
-          saga_offenders = history.fetch(:saga_dispatches, []).filter_map do |entry|
+          offenders = saga_binding_offenders(history) + policy_binding_offenders(history)
+          offenders.empty? || offenders.join("; ")
+        end
+
+        # One message per saga dispatch whose bound args differ from the re-derivation.
+        def saga_binding_offenders(history)
+          history.fetch(:saga_dispatches, []).filter_map do |entry|
             expected = resolve_dispatch_binding(entry)
             next if expected == entry[:args]
 
@@ -49,17 +67,17 @@ module Hecks
               "bound #{entry[:args].inspect}, but independently re-deriving with_spec's own resolution gives " \
               "#{expected.inspect}"
           end
+        end
 
-          policy_offenders = history.fetch(:policy_dispatches, []).filter_map do |entry|
+        # One message per policy dispatch whose bound args differ from the re-derivation.
+        def policy_binding_offenders(history)
+          history.fetch(:policy_dispatches, []).filter_map do |entry|
             expected = resolve_trigger_binding(entry)
             next if expected == entry[:args]
 
             "#{entry[:policy]} on #{entry[:on]} — bound #{entry[:args].inspect}, but independently re-deriving " \
               "with_spec's own resolution gives #{expected.inspect}"
           end
-
-          offenders = saga_offenders + policy_offenders
-          offenders.empty? || offenders.join("; ")
         end
 
         # Re-derives SagaInterpreter#dispatch_args: a literal, the correlation key,
@@ -106,33 +124,44 @@ module Hecks
         #   naming each offending mutation
         def mutations_match_recompute(history)
           bluebooks = history.fetch(:bluebooks)
+          offenders = history.fetch(:mutation_traces, []).flat_map { |entry| mutation_offenders(bluebooks, entry) }
+          offenders.empty? || offenders.join("; ")
+        end
 
-          offenders = history.fetch(:mutation_traces, []).flat_map do |entry|
-            next [] unless entry[:after]
+        # One message per recomputable mutation of `entry` whose real after-state differs.
+        def mutation_offenders(bluebooks, entry)
+          return [] unless entry[:after]
 
-            command = command_for_verb(bluebooks, entry[:verb])
-            next [] unless command
+          context = mutation_context(bluebooks, entry)
+          return [] unless context
 
-            aggregate = aggregate_for_verb(bluebooks, entry[:verb])
-            next [] unless aggregate
+          recomputable = context.command.mutations.select { |m| RECOMPUTABLE_MUTATION_OPS.include?(m.op) }
+          recomputable.filter_map { |mutation| mutation_offender(mutation, entry, context) }
+        end
 
-            owner = owner_for_verb(bluebooks, entry[:verb]) || aggregate
+        # What recomputing `entry` needs, or nil when its verb names no command or aggregate.
+        def mutation_context(bluebooks, entry)
+          command = command_for_verb(bluebooks, entry[:verb])
+          return unless command
 
-            args = with_declared_defaults(command, entry[:args])
-            command.mutations.select { |m| RECOMPUTABLE_MUTATION_OPS.include?(m.op) }.filter_map do |mutation|
-              expected = recompute_mutation(mutation, entry[:before][mutation.target], args, entry[:before],
-                                            aggregate, command, owner)
-              next if expected == :unrecomputable
+          aggregate = aggregate_for_verb(bluebooks, entry[:verb])
+          return unless aggregate
 
-              actual = entry[:after][mutation.target]
-              next if symbolize_deep(expected) == symbolize_deep(actual)
+          owner = owner_for_verb(bluebooks, entry[:verb]) || aggregate
+          MutationRecompute::Context.new(aggregate, command, owner, entry[:before],
+                                         with_declared_defaults(command, entry[:args]))
+        end
 
-              "#{entry[:verb]} — #{mutation.op} on #{mutation.target} — recomputing independently gives " \
-                "#{expected.inspect}, but the real dispatch left #{actual.inspect}"
-            end
-          end
+        # The message for one mutation whose recomputation disagrees with the real dispatch.
+        def mutation_offender(mutation, entry, context)
+          expected = recompute_mutation(mutation, entry[:before][mutation.target], context)
+          return if expected == :unrecomputable
 
-          offenders.empty? || offenders.join("; ")
+          actual = entry[:after][mutation.target]
+          return if symbolize_deep(expected) == symbolize_deep(actual)
+
+          "#{entry[:verb]} — #{mutation.op} on #{mutation.target} — recomputing independently gives " \
+            "#{expected.inspect}, but the real dispatch left #{actual.inspect}"
         end
 
         # The arguments the command actually ran with: an argument the caller left out takes the
@@ -174,156 +203,6 @@ module Hecks
           entity_name, = command_path.split(".", 2)
           aggregate.entities.find { |candidate| candidate.hecks_name == entity_name }
         end
-
-        # Dispatches to the recompute rule for `mutation.op`.
-        def recompute_mutation(mutation, current, args, before_scope, aggregate, command, owner = aggregate)
-          case mutation.op
-          when :append
-            recompute_append(current, mutation.source, before_scope, args, aggregate, command, owner, mutation.target)
-          when :remove   then recompute_remove(current, mutation.source, args)
-          when :multiply then recompute_multiply(current, resolve_mutation_source(mutation.source, args))
-          when :clamp    then recompute_clamp(current, mutation.source)
-          when :set      then recompute_set(mutation.source, args, aggregate, owner, 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, args, aggregate, owner, target)
-          raw = resolve_mutation_source(source, args)
-          attribute = owner&.attribute(target)
-          coerced = attribute ? Runtime::Value.for_attribute(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, before_scope, args, aggregate, command, owner = aggregate, target = nil)
-          fields = source_map.transform_values do |source|
-            resolve_mutation_append_field(source, before_scope, args, aggregate, command)
-          end
-          fill_recompute_declared_defaults(aggregate, owner, 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(aggregate, owner, target, fields)
-          return fields unless target
-
-          element_type = owner&.attribute(target)&.type
-          return fields unless element_type
-
-          entity = owner.entities.find { |piece| piece.hecks_name == element_type.to_s }
-          if entity
-            entity.attributes.each do |attribute|
-              next if fields.key?(attribute.name)
-
-              fields[attribute.name] = attribute.list? ? [] : Runtime::Instance.default_for(aggregate, attribute)
-            end
-            return fields
-          end
-
-          value_object = aggregate.value_object(element_type)
-          return fields unless value_object
-
-          Runtime::Value.apply_defaults(value_object, fields)
-        end
-
-        # Resolves one appended field's value from its declared source.
-        def resolve_mutation_append_field(source, before_scope, args, aggregate, command)
-          return source unless source.is_a?(Symbol)
-          return before_scope[source] unless args.key?(source)
-
-          coerce_recompute_append_arg(aggregate, command, source, 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(aggregate, command, source, raw)
-          attribute = command.attribute(source)
-          return raw unless attribute
-
-          Runtime::Value.materialize(Runtime::Value.for_attribute(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)
-
-          current ||= 0
-          if current.is_a?(Hash)
-            field = current.keys.find { |f| current[f].is_a?(Numeric) }
-            return :unrecomputable unless field
-
-            current.merge(field => current[field] * amount)
-          elsif current.is_a?(Numeric)
-            current * amount
-          else
-            :unrecomputable
-          end
-        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
-          current ||= 0
-          if current.is_a?(Hash)
-            field = current.keys.find { |f| current[f].is_a?(Numeric) }
-            return :unrecomputable unless field
-
-            current.merge(field => current[field].clamp(min, max))
-          elsif current.is_a?(Numeric)
-            current.clamp(min, max)
-          else
-            :unrecomputable
-          end
-        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

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

@@ -0,0 +1,69 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Independent nestings of a `group_by` read model's rows, for
+      # `InvariantsAndAggregation#group_by_matches_recompute` to compare against the answer.
+      module GroupByRecompute
+        # Judges one `group_by` ask against the rows it was eligible to see:
+        # refused exactly when two of them share a checked key path, and
+        # otherwise nested exactly as `nest_rows` nests them.
+        def group_by_offense(bluebook, asked, model, grouped_head)
+          rows = eligible_rows(bluebook, asked.fetch(:instances_at), model, grouped_head, asked[:args] || {})
+          materialized = rows.map { |state| Runtime::Value.materialize_unwrapped(state) }
+          shared = shared_key_paths(materialized, model.group_by_fields)
+          return nesting_offense(asked, model, grouped_head, materialized) if shared.empty?
+
+          collision_offense(asked, model.group_by_fields, shared.length, checked_key_paths?(bluebook, model, grouped_head))
+        end
+
+        # Whether the grouped key paths are checked, i.e. do not cover the head's identity.
+        def checked_key_paths?(bluebook, model, grouped_head)
+          !model.groups_by_identity?(bluebook.aggregate(grouped_head[:aggregate]))
+        end
+
+        # Judges an ask with no shared key path: it must not have refused, and its grouping must
+        # equal the independent nesting.
+        def nesting_offense(asked, model, grouped_head, materialized)
+          return nil if asked[:error]
+          return nil if asked[:rows]&.first&.dig(grouped_head[:as]) == nest_rows(materialized, model.group_by_fields)
+
+          "#{asked[:query]} #{asked[:args].inspect} answered a #{grouped_head[:as]} grouping that disagrees " \
+            "with independently nesting group_by #{model.group_by_fields.inspect} over #{materialized.length} " \
+            "eligible row(s)"
+        end
+
+        # Judges an ask whose eligible rows share at least one full key path:
+        # a checked key path must have refused, and an identity-covering one
+        # cannot be shared by rows that hold their identity.
+        def collision_offense(asked, fields, shared, checked)
+          return nil if checked && asked[:error]
+
+          "#{asked[:query]} #{asked[:args].inspect} #{checked ? "answered" : "reached"}, but #{shared} key " \
+            "path(s) of group_by #{fields.inspect} are shared by more than one eligible row, " \
+            "#{checked ? "so the ask must refuse" : "though they cover the identity"}"
+        end
+
+        # Every full `group_by` key path more than one row reaches, found by
+        # tallying each row's tuple of grouped values, with no nesting at all.
+        def shared_key_paths(rows, fields)
+          rows.map { |row| fields.map { |field| row[field] } }.tally.select { |_, count| count > 1 }.keys
+        end
+
+        # One level of nesting per `group_by` field in declared order; the leaf
+        # is the row with every grouped field stripped. Called only when no key
+        # path is shared (`shared_key_paths` rules that out), so each leaf holds
+        # exactly one row; a second row raises rather than being picked over.
+        def nest_rows(rows, fields)
+          field, *rest = fields
+          rows.group_by { |row| row[field] }.transform_values do |group|
+            stripped = group.map { |row| row.reject { |key, _| key == field } }
+            next nest_rows(stripped, rest) unless rest.empty?
+            raise ArgumentError, "nest_rows reached a key path #{stripped.length} rows share" unless stripped.length == 1
+
+            stripped[0]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,134 +1,102 @@
+require_relative "tenant_scope"
+
 module Hecks
   module Fuzzing
     module Properties
       # Guard and authorization properties over a replayed history: refusals name declared rules,
       # tenant scoping holds, and guard violations are refused.
       module Guards
+        include TenantScope
+
         # Checks tenant-scoped query answers and refusals against TenantScope.apply's contract.
         #
         # Uses hand-built fixtures: the only corpus query declaring `authorize` takes no
         # attributes, so the generator cannot supply a `tenant:`.
-        # rubocop:disable-next Metrics/CyclomaticComplexity
-        # rubocop:disable-next Metrics/PerceivedComplexity
         #
         # @param history [Hash] a replayed history as returned by `Replay.call`
         # @return [true, String] true if every answer and refusal agrees with the contract
         def authorize_scopes_or_refuses(history)
           bluebooks = history.fetch(:bluebooks)
-
-          offenders = history.fetch(:queries).filter_map do |asked|
-            next unless asked[:query].is_a?(String) && asked[:query].include?("::")
-
-            declared = query_for_verb(bluebooks, asked[:query])
-            authorization = declared&.authorization
-            tenant = authorization&.tenant&.to_sym
-            next unless tenant
-
-            args = asked[:args] || {}
-            tenant_given = args.key?(tenant)
-
-            if asked[:error]
-              next if tenant_given
-              next if asked[:error].to_s.include?("declares authorize with tenant: #{tenant}")
-
-              "#{asked[:query]} #{args.inspect} refused with no #{tenant}: given, but not with the declared " \
-                "tenant_required wording (#{asked[:error]})"
-            elsif !tenant_given
-              "#{asked[:query]} #{args.inspect} answered successfully with no #{tenant}: given, but #{declared.name} " \
-                "declares authorize with tenant: #{tenant}"
-            else
-              wanted = args[tenant].to_s
-              mismatched = asked[:rows].find do |row|
-                Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, tenant)).to_s != wanted
-              end
-              next unless mismatched
-
-              "#{asked[:query]} #{args.inspect} answered a row whose #{tenant} disagrees with the given " \
-                "#{wanted.inspect}: #{mismatched.inspect}"
-            end
-          end
-
+          offenders = history.fetch(:queries).filter_map { |asked| authorize_offense(bluebooks, asked) }
           offenders.empty? || offenders.join("; ")
         end
 
-        # Raised classes that mark a guard refusal; the message alone cannot tell it from
-        # the other "X refused — Y" wordings.
-        GUARD_REFUSAL_KINDS = %w[Hecks::Runtime::GivenNotMet Hecks::Runtime::EnsuresNotMet].freeze
+        # The message for one query answer that breaks the tenant contract, or nil.
+        def authorize_offense(bluebooks, asked)
+          declared = declared_query(bluebooks, asked)
+          tenant = query_tenant(declared)
+          return unless tenant
 
-        # Checks that every given/ensures refusal quotes a description its command declares.
-        def guard_refusals_are_declared(history)
-          bluebooks = history.fetch(:bluebooks)
+          args = asked[:args] || {}
+          return refusal_offense(asked, args, tenant) if asked[:error]
+          return unscoped_answer_offense(asked, args, tenant, declared) unless args.key?(tenant)
 
-          offenders = history.fetch(:refusals).filter_map do |refusal|
-            next unless GUARD_REFUSAL_KINDS.include?(refusal[:kind])
-
-            match = refusal[:error].to_s.match(/\A(.+) refused — (.+)\z/)
-            next "#{refusal[:verb]} raised #{refusal[:kind]} with unparseable message #{refusal[:error].inspect}" unless match
-
-            command = command_for_verb(bluebooks, refusal[:verb])
-            next "#{refusal[:verb]} raised #{refusal[:kind]}, but no declared command resolves that verb" unless command
-
-            declared = effective_guard_descriptions(bluebooks, refusal[:verb], command)
-            next if declared.include?(match[2])
+          mismatched_row_offense(asked, args, tenant)
+        end
 
-            "#{refusal[:verb]} refused — #{match[2].inspect} — but #{command.hecks_name} declares no given " \
-              "or ensures with that description (it declares #{declared.inspect})"
-          end
+        def declared_query(bluebooks, asked)
+          query_for_verb(bluebooks, asked[:query]) if asked[:query].is_a?(String) && asked[:query].include?("::")
+        end
 
-          offenders.empty? || offenders.join("; ")
+        def query_tenant(declared)
+          authorization = declared&.authorization
+          authorization&.tenant&.to_sym
         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.
-        # rubocop:disable-next Metrics/CyclomaticComplexity
-        # rubocop:disable-next Metrics/PerceivedComplexity
-        def commands_respect_tenant_scope(history)
-          bluebooks = history.fetch(:bluebooks)
-          instances = history.fetch(:instances)
+        def refusal_offense(asked, args, tenant)
+          return if args.key?(tenant)
+          return if asked[:error].to_s.include?("declares authorize with tenant: #{tenant}")
 
-          offenders = instances.flat_map do |key, state|
-            domain_name    = key.split("::").first
-            aggregate_name = key.split("::").last.split("#").first
-            aggregate      = bluebooks[domain_name]&.aggregate(aggregate_name)
-            next [] unless aggregate
+          "#{asked[:query]} #{args.inspect} refused with no #{tenant}: given, but not with the declared " \
+            "tenant_required wording (#{asked[:error]})"
+        end
 
-            own_tenant_field = tenant_field_for(aggregate)
-            next [] unless own_tenant_field && state.key?(own_tenant_field)
+        def unscoped_answer_offense(asked, args, tenant, declared)
+          "#{asked[:query]} #{args.inspect} answered successfully with no #{tenant}: given, but #{declared.name} " \
+            "declares authorize with tenant: #{tenant}"
+        end
 
-            own_tenant = Ports::Query::InMemory.comparable(state[own_tenant_field])
+        def mismatched_row_offense(asked, args, tenant)
+          wanted = args[tenant].to_s
+          mismatched = asked[:rows].find do |row|
+            Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(row, tenant)).to_s != wanted
+          end
+          return unless mismatched
 
-            aggregate.attributes.filter_map do |attribute|
-              next unless attribute.type.is_a?(Bluebook::Reference)
+          "#{asked[:query]} #{args.inspect} answered a row whose #{tenant} disagrees with the given " \
+            "#{wanted.inspect}: #{mismatched.inspect}"
+        end
 
-              target = bluebooks[domain_name]&.aggregate(attribute.type.target_name)
-              target_tenant_field = target && tenant_field_for(target)
-              next unless target_tenant_field
+        # Raised classes that mark a guard refusal; the message alone cannot tell it from
+        # the other "X refused — Y" wordings.
+        GUARD_REFUSAL_KINDS = %w[Hecks::Runtime::GivenNotMet Hecks::Runtime::EnsuresNotMet].freeze
 
-              target_id = state[attribute.name]
-              next unless target_id
+        # Checks that every given/ensures refusal quotes a description its command declares.
+        def guard_refusals_are_declared(history)
+          bluebooks = history.fetch(:bluebooks)
+          offenders = history.fetch(:refusals).filter_map { |refusal| guard_refusal_offense(bluebooks, refusal) }
+          offenders.empty? || offenders.join("; ")
+        end
 
-              target_state = instances["#{domain_name}::#{target.name}##{target_id}"]
-              next unless target_state&.key?(target_tenant_field)
+        # The message for one guard refusal whose quoted description is not declared, or nil.
+        def guard_refusal_offense(bluebooks, refusal)
+          return unless GUARD_REFUSAL_KINDS.include?(refusal[:kind])
 
-              target_tenant = Ports::Query::InMemory.comparable(target_state[target_tenant_field])
-              next if target_tenant == own_tenant
+          match = refusal[:error].to_s.match(/\A(.+) refused — (.+)\z/)
+          return "#{refusal[:verb]} raised #{refusal[:kind]} with unparseable message #{refusal[:error].inspect}" unless match
 
-              "#{key} (#{own_tenant_field}: #{own_tenant.inspect}) references #{attribute.name}: #{target_id.inspect}, " \
-                "but #{domain_name}::#{target.name}##{target_id} carries #{target_tenant_field}: " \
-                "#{target_tenant.inspect} — a cross-tenant write nothing refused"
-            end
-          end
+          command = command_for_verb(bluebooks, refusal[:verb])
+          return "#{refusal[:verb]} raised #{refusal[:kind]}, but no declared command resolves that verb" unless command
 
-          offenders.empty? || offenders.join("; ")
+          undeclared_guard_offense(bluebooks, refusal, match[2], command)
         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
+        def undeclared_guard_offense(bluebooks, refusal, description, command)
+          declared = effective_guard_descriptions(bluebooks, refusal[:verb], command)
+          return if declared.include?(description)
+
+          "#{refusal[:verb]} refused — #{description.inspect} — but #{command.hecks_name} declares no given " \
+            "or ensures with that description (it declares #{declared.inspect})"
         end
 
         # A command's own guard descriptions plus those of every command it delegates to.
@@ -150,19 +118,19 @@ module Hecks
           domain, aggregate_name, command_path = Naming.split_verb(verb)
           return nil unless command_path
 
-          bluebook = bluebooks[domain]
-          return nil unless bluebook
-
-          aggregate = bluebook.aggregate(aggregate_name)
+          aggregate = bluebooks[domain]&.aggregate(aggregate_name)
           return nil unless aggregate
 
-          if command_path.include?(".")
-            entity_name, sub = command_path.split(".", 2)
-            entity = aggregate.entities.find { |e| e.hecks_name == entity_name }
-            entity&.command(sub)
-          else
-            aggregate.command(command_path)
-          end
+          command_in(aggregate, command_path)
+        end
+
+        # The command a dotted or plain path names under `aggregate`: an entity's own command
+        # when the path names an entity.
+        def command_in(aggregate, command_path)
+          return aggregate.command(command_path) unless command_path.include?(".")
+
+          entity_name, sub = command_path.split(".", 2)
+          aggregate.entities.find { |e| e.hecks_name == entity_name }&.command(sub)
         end
 
         # Recomputes enforce_givens/enforce_lifecycle_guard against Replay's pre-dispatch
@@ -178,8 +146,8 @@ module Hecks
             next if check[:recomputed_refused] == check[:actual_refused]
 
             "#{check[:verb]} — independently recomputing enforce_givens/enforce_lifecycle_guard against the " \
-              "pre-dispatch state says #{check[:recomputed_refused] ? "refused (#{check[:recomputed_kind]})" : 'admitted'}, " \
-              "but the real dispatch #{check[:actual_refused] ? "refused (#{check[:actual_kind]})" : 'admitted it'}"
+              "pre-dispatch state says #{check[:recomputed_refused] ? "refused (#{check[:recomputed_kind]})" : "admitted"}, " \
+              "but the real dispatch #{check[:actual_refused] ? "refused (#{check[:actual_kind]})" : "admitted it"}"
           end
 
           offenders.empty? || offenders.join("; ")