hecks 3.5.0 → 3.7.0

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("; ")

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

@@ -1,90 +1,61 @@
+require "json"
+require_relative "aggregation_recompute"
+require_relative "group_by_recompute"
+require_relative "piece_invariants"
+
 module Hecks
   module Fuzzing
     module Properties
       # Stored-record, saga-rehydration, fan-out, and read-model-aggregation
       # properties, extended into Properties.
       module InvariantsAndAggregation
+        include AggregationRecompute
+        include GroupByRecompute
+        include PieceInvariants
+
         # Every stored record — and every entity nested inside it — still
         # satisfies its own declared invariants, re-checked independently of
         # whichever call site (Admissibility#enforce_invariants) was supposed
         # to have refused a violation live.
         def stored_records_satisfy_declared_invariants(history)
           bluebooks = history.fetch(:bluebooks)
-
-          offenders = history.fetch(:instances).filter_map do |key, state|
-            domain_name    = key.split("::").first
-            aggregate_name = key.split("::").last.split("#").first
-            bluebook       = bluebooks[domain_name]
-            aggregate      = bluebook&.aggregate(aggregate_name)
-            next unless aggregate
-
-            violated = aggregate.invariants.find do |invariant|
-              !Bluebook::Expression::Evaluator.call(invariant.canonical, state)
-            end
-            next "#{key} violates #{aggregate_name}'s own declared invariant #{violated.description.inspect}" if violated
-
-            check_piece_invariants(aggregate, state, key)
-          end
-
+          offenders = history.fetch(:instances).filter_map { |key, state| stored_record_offense(bluebooks, key, state) }
           offenders.empty? || offenders.join("; ")
         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 = owner_construct.attributes.find { |a| a.list? && a.type.to_s == entity.hecks_name }
-            next unless list_attr
-
-            Array(owner_state[list_attr.name]).each do |element|
-              violated = entity.invariants.find do |invariant|
-                !Bluebook::Expression::Evaluator.call(invariant.canonical, element)
-              end
-              if violated
-                return "#{key}'s own #{entity.hecks_name} violates its declared invariant " \
-                       "#{violated.description.inspect}"
-              end
-
-              nested = check_piece_invariants(entity, element, key)
-              return nested if nested
-            end
-          end
-          nil
-        end
-
         # A saga instance's own state is one the process manager declares, and
         # its memory survives the same JSON round-trip `SagaInterpreter#checkpoint`'s
         # own `deep_copy` performs (mirrored here, a private instance method
         # with no registry to hand it).
         def sagas_rehydrate_cleanly(history)
-          bluebook = history.fetch(:bluebook)
-          process_managers = bluebook.process_managers.to_h { |pm| [pm.name, pm] }
+          process_managers = history.fetch(:bluebook).process_managers.to_h { |pm| [pm.name, pm] }
 
           offenders = history.fetch(:saga_instances).flat_map do |pm_name, conversations|
-            pm = process_managers[pm_name]
-
             conversations.filter_map do |correlation, instance|
-              problems = []
+              saga_offense(pm_name, process_managers[pm_name], correlation, instance)
+            end
+          end
 
-              problems << "holds state #{instance[:state].inspect}, which #{pm_name} never declares" \
-                if pm && !pm.declares_state?(instance[:state])
+          offenders.empty? || offenders.join("; ")
+        end
 
-              rehydrated = JSON.parse(JSON.generate(instance[:memory]), symbolize_names: true)
-              if rehydrated != instance[:memory]
-                problems << "memory does not survive its own checkpoint round-trip " \
-                            "(checkpointed #{instance[:memory].inspect}, rehydrated #{rehydrated.inspect})"
-              end
+        # The message for one saga conversation that breaks, or nil.
+        def saga_offense(pm_name, manager, correlation, instance)
+          problems = saga_problems(pm_name, manager, instance)
+          "#{pm_name}##{correlation.inspect}: #{problems.join(" and ")}" unless problems.empty?
+        end
 
-              next if problems.empty?
+        def saga_problems(pm_name, manager, instance)
+          problems = []
+          problems << "holds state #{instance[:state].inspect}, which #{pm_name} never declares" \
+            if manager && !manager.declares_state?(instance[:state])
 
-              "#{pm_name}##{correlation.inspect}: #{problems.join(' and ')}"
-            end
+          rehydrated = JSON.parse(JSON.generate(instance[:memory]), symbolize_names: true)
+          if rehydrated != instance[:memory]
+            problems << "memory does not survive its own checkpoint round-trip " \
+                        "(checkpointed #{instance[:memory].inspect}, rehydrated #{rehydrated.inspect})"
           end
-
-          offenders.empty? || offenders.join("; ")
+          problems
         end
 
         # A `for_each` policy dispatches exactly once per row its declared query
@@ -92,23 +63,25 @@ module Hecks
         # computation. `expected_row_ids` is `nil`, not `[]`, when `policy.where`
         # never held — no dispatch is the claim then, not "dispatched to zero rows."
         def fanout_dispatches_once_per_matching_row(history)
-          offenders = history.fetch(:fan_outs).filter_map do |finding|
-            expected = finding[:expected_row_ids]
-            actual   = finding[:actual_row_ids].sort
-
-            if expected.nil?
-              next if actual.empty?
+          offenders = history.fetch(:fan_outs).filter_map { |finding| fan_out_offense(finding) }
+          offenders.empty? || offenders.join("; ")
+        end
 
-              next "#{finding[:policy]} on #{finding[:on]}: where did not hold, but dispatched to #{actual.inspect}"
-            end
+        # The message for one fan-out whose dispatches differ from the expectation, or nil.
+        def fan_out_offense(finding)
+          expected = finding[:expected_row_ids]
+          actual   = finding[:actual_row_ids].sort
+          return unexpected_dispatch_offense(finding, actual) if expected.nil?
+          return if actual == expected
 
-            next if actual == expected
+          "#{finding[:policy]} on #{finding[:on]}: for_each answered #{expected.inspect}, " \
+            "but the reaction log shows dispatches to #{actual.inspect}"
+        end
 
-            "#{finding[:policy]} on #{finding[:on]}: for_each answered #{expected.inspect}, " \
-              "but the reaction log shows dispatches to #{actual.inspect}"
-          end
+        def unexpected_dispatch_offense(finding, actual)
+          return if actual.empty?
 
-          offenders.empty? || offenders.join("; ")
+          "#{finding[:policy]} on #{finding[:on]}: where did not hold, but dispatched to #{actual.inspect}"
         end
 
         # A `count`/`median` report's reduced scalar matches the same reduction
@@ -116,72 +89,31 @@ module Hecks
         # and InMemory.comparable/.holds? — the same calls the interpreter
         # itself makes, so this oracle can't drift from what a field read or a
         # `where` clause means without the interpreter drifting identically.
-        # rubocop:disable-next Metrics/CyclomaticComplexity
-        # rubocop:disable-next Metrics/PerceivedComplexity
         def aggregation_matches_recompute(history)
           bluebook = history.fetch(:bluebook)
-
-          offenders = history.fetch(:queries).filter_map do |asked|
-            next if asked[:error]
-
-            domain, name = asked[:query].to_s.split(".", 2)
-            next unless name && domain == bluebook.name
-
-            model = bluebook.read_model(name)
-            next unless model&.reducing?
-
-            reduced_head = model.aggregate_heads.find { |head| head[:many] }
-            next unless reduced_head
-
-            rows = eligible_rows(bluebook, asked.fetch(:instances_at), domain, model, reduced_head, asked[:args] || {})
-            expected = recompute_reduction(model, rows)
-            actual = asked[:rows]&.first&.dig(reduced_head[:as])
-            next if actual == expected
-
-            "#{asked[:query]} #{asked[:args].inspect} answered #{actual.inspect} for #{reduced_head[:as]}, " \
-              "but recomputing independently from #{rows.length} eligible row(s) gives #{expected.inspect}"
-          end
-
+          offenders = history.fetch(:queries).filter_map { |asked| aggregation_offense(bluebook, asked) }
           offenders.empty? || offenders.join("; ")
         end
 
-        # ADR 0078's siblings of `count`/`median`, each an independent fold over the same
-        # eligible rows — never reusing ReadModelInterpreter#reduce's own arithmetic, only the
-        # shared field-reading primitives `recompute_median` already relied on.
-        def recompute_reduction(model, rows)
-          return rows.length if model.count?
-          return recompute_median(rows, model.median_field) if model.median_field
-          return recompute_values(rows, model.sum_field).sum if model.sum_field
-          return recompute_avg(rows, model.avg_field) if model.avg_field
-          return recompute_values(rows, model.min_field).min if model.min_field
-          return recompute_values(rows, model.max_field).max if model.max_field
-          return recompute_percentile(rows, model.percentile_field, model.percentile_at) if model.percentile_field
-          return recompute_values(rows, model.any_field).any? if model.any_field
+        # The message for one reducing ask whose answer disagrees with the recomputation, or nil.
+        def aggregation_offense(bluebook, asked)
+          return if asked[:error]
 
-          recompute_values(rows, model.all_field).all?
-        end
-
-        def recompute_values(rows, field)
-          rows.map { |state| Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(state, field)) }.compact
-        end
+          model = asked_read_model(bluebook, asked)
+          return unless model&.reducing?
 
-        def recompute_avg(rows, field)
-          values = recompute_values(rows, field)
-          values.empty? ? nil : values.sum.to_f / values.length
+          reduced_head = many_head(model)
+          reduced_head && reduction_offense(bluebook, asked, model, reduced_head)
         end
 
-        # Same linear-interpolation formula as `ReadModelInterpreter#percentile`, written
-        # independently here rather than called, for the same reason `recompute_median`
-        # already is: an oracle that calls the interpreter's own fold agrees with a bug in it
-        # by construction (ADR 0061's `nest_rows` lesson).
-        def recompute_percentile(rows, field, at)
-          values = recompute_values(rows, field).sort
-          return nil if values.empty?
+        def reduction_offense(bluebook, asked, model, reduced_head)
+          rows = eligible_rows(bluebook, asked.fetch(:instances_at), model, reduced_head, asked[:args] || {})
+          expected = recompute_reduction(model, rows)
+          actual = asked[:rows]&.first&.dig(reduced_head[:as])
+          return if actual == expected
 
-          position = at * (values.length - 1)
-          lower = position.floor
-          fraction = position - lower
-          fraction.zero? ? values[lower] : values[lower] + (fraction * (values[lower + 1] - values[lower]))
+          "#{asked[:query]} #{asked[:args].inspect} answered #{actual.inspect} for #{reduced_head[:as]}, " \
+            "but recomputing independently from #{rows.length} eligible row(s) gives #{expected.inspect}"
         end
 
         # aggregation_matches_recompute's own shape, extended from reducing a
@@ -190,109 +122,16 @@ module Hecks
         # path not covering identity means the ask must have refused.
         def group_by_matches_recompute(history)
           bluebook = history.fetch(:bluebook)
-
-          offenders = history.fetch(:queries).filter_map do |asked|
-            domain, name = asked[:query].to_s.split(".", 2)
-            next unless name && domain == bluebook.name
-
-            model = bluebook.read_model(name)
-            next unless model&.group_by&.any?
-
-            grouped_head = model.aggregate_heads.find { |head| head[:many] }
-            next unless grouped_head
-
-            group_by_offense(bluebook, asked, model, grouped_head)
-          end
-
+          offenders = history.fetch(:queries).filter_map { |asked| group_by_ask_offense(bluebook, asked) }
           offenders.empty? || offenders.join("; ")
         end
 
-        # 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), bluebook.name, model, grouped_head, asked[:args] || {})
-          materialized = rows.map { |state| Runtime::Value.materialize_unwrapped(state) }
-          shared = shared_key_paths(materialized, model.group_by_fields)
-          checked = !model.groups_by_identity?(bluebook.aggregate(grouped_head[:aggregate]))
-          return collision_offense(asked, model.group_by_fields, shared.length, checked) if shared.any?
-          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 #{rows.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
-
-        # The eligible rows a `count`/`median` head reduces: every instance of
-        # the reduced head's own aggregate, FK-matched against the report's root
-        # reference (if any), then narrowed by the report's own `where` clauses.
-        def eligible_rows(bluebook, instances, domain, model, reduced_head, args)
-          aggregate = bluebook.aggregate(reduced_head[:aggregate])
-          prefix = "#{domain}::#{reduced_head[:aggregate]}#"
-          # `id:` merged in, the same shape every live head row carries —
-          # count/median never read it, but group_by's own nesting does.
-          rows = instances.filter_map { |key, state| state.merge(id: key.split("#").last) if key.start_with?(prefix) }
-
-          if model.reference_target
-            reference_id = args[model.reference_name].to_s
-            fk_fields = aggregate.attributes.select do |attribute|
-              attribute.reference? && attribute.type.target_name == model.reference_target.to_s
-            end.map(&:name)
-
-            rows = rows.select { |state| fk_fields.any? { |field| state[field].to_s == reference_id } }
-          end
-
-          rows.select do |state|
-            model.wheres.all? do |clause|
-              held = Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(state, clause.field))
-              Ports::Query::InMemory.holds?(clause, held, args)
-            end
-          end
-        end
-
-        # ReadModelInterpreter#median's own definition, reproduced: the true
-        # middle for an odd count, the average of the two middles for an even
-        # count, `nil` for empty — never zero, so "nothing" isn't "zero."
-        def recompute_median(rows, field)
-          values = rows.map { |state| Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(state, field)) }
-                       .compact.sort
-          return nil if values.empty?
+        def group_by_ask_offense(bluebook, asked)
+          model = asked_read_model(bluebook, asked)
+          return unless model&.group_by&.any?
 
-          middle = values.length / 2
-          values.length.odd? ? values[middle] : (values[middle - 1] + values[middle]) / 2.0
+          grouped_head = many_head(model)
+          grouped_head && group_by_offense(bluebook, asked, model, grouped_head)
         end
       end
     end