hecks 1.0.2 → 1.1.0

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

@@ -0,0 +1,251 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Guard/authorization properties: every given/ensures refusal a run
+      # actually raised names a rule the refusing command actually declares,
+      # a scope-authorized answer (or its refusal) is correctly worded, and
+      # a lifecycle guard's own violation is refused rather than silently
+      # admitted.
+
+      # Holds authorize_scopes_or_refuses, guard_refusals_are_declared, and
+      # lifecycle_guard_and_given_violations_are_refused, plus the shared
+      # verb-to-declaration lookups (#command_for_verb,
+      # #effective_guard_descriptions) each resolves a refusal against.
+      module Guards
+        # `Query#options`' OTHER HALF — TenantScope.apply's own contract
+        # (tenant_scope.rb), independently restated as a property rather
+        # than exercised only through whatever the generator happens to
+        # try. NOT closed by the generator here on purpose: SafeDepositBox.
+        # Rented — the only real corpus query declaring `authorize` at
+        # all — declares ZERO attributes of its own, so StepBuilder#args_for
+        # always hands it `{}` and TenantScope.apply refuses every
+        # generated attempt, unconditionally (confirmed: no successful ask
+        # against an authorize-bearing query reaches this property via the
+        # standard battery today). Extending the generator to invent a
+        # `tenant:` value ran into a separate, real finding along the way —
+        # SafeDepositBox is COMPOSITE-identified (`identified_by` is nil
+        # for it — Runtime::Identified#derive_identity), so the generator's
+        # existing `known_ids` pool (keyed by `aggregate.identified_by ||
+        # "id"`) tracks a stray, never-real scalar for it rather than its
+        # true `branch_code`+`box_number` pair — a second, narrower
+        # generator gap this property does not attempt to fix, since fixing
+        # it well enough to trust a generated `tenant:` value would be the
+        # heavier, "benefits every future property" path the plan itself
+        # names as the alternative. Hand-built fixtures close the real
+        # claim directly instead: faster, narrower, and correct either way,
+        # since TenantScope.apply's contract is identical regardless of
+        # where a `tenant:` arg came from.
+        #
+        # Two claims, matching TenantScope.apply's own two branches: every
+        # SUCCESSFUL answer's own tenant field agrees with the tenant arg
+        # given (the WhereClause TenantScope injects is a Symbol reference
+        # into args, resolved dynamically — this checks the OUTCOME, not
+        # re-deriving that resolution) ; every ask MISSING a required
+        # tenant: refuses with the declared wording, never succeeds. A
+        # refusal for an unrelated reason with the tenant arg present is
+        # not this property's claim either way — skipped, not graded.
+        # The three mutually exclusive outcomes ("refused, was it for the
+        # declared reason?" / "succeeded without a tenant that was
+        # required?" / "succeeded with a tenant, does every row actually
+        # agree with it?") map exactly onto TenantScope.apply's own two
+        # branches, per the comment above — splitting them into separate
+        # methods would mean threading `asked`, `tenant`, `args`, and
+        # `declared` out to each one for no gain, since none of the three
+        # branches shares logic with the others beyond that shared setup.
+        # rubocop:disable-next Metrics/CyclomaticComplexity
+        # rubocop:disable-next Metrics/PerceivedComplexity
+        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.empty? || offenders.join("; ")
+        end
+
+        # EVERY GIVEN/ENSURES REFUSAL A RUN ACTUALLY RAISED NAMES A RULE
+        # THE COMMAND ACTUALLY DECLARES. `GivenNotMet`/`EnsuresNotMet` both
+        # quote their guard's own `description` verbatim
+        # (command_rules/admissibility.rb: `"#{command.hecks_name} refused
+        # — #{given.description}"`) — the SAME text `behavior.bluebook`'s
+        # own `Rule`/Command.Ensure hold as `Rule#description`, so a
+        # refusal whose quoted text is not among the refusing command's
+        # OWN `guard_descriptions` (Behaviour::Command, both givens and
+        # ensures) is either a stale message surviving a renamed rule, a
+        # rule firing against the wrong command's own guard set, or the
+        # wording drifting out from under the declaration it is supposed
+        # to quote — banking's own 128 status givens (customer/account
+        # guards, some through a cross-aggregate dereference) are exactly
+        # the surface this exists to hold to its word.
+        #
+        # `kind:` is what tells a guard refusal apart from the FOUR other
+        # `RefusalWording` templates sharing the identical "X refused — Y"
+        # shape (LifecycleRefused/transition_blocked, both TypeMismatch
+        # object-reference templates, Unauthorized/role_mismatch) — see
+        # Replay's own comment at the refusal rescue site. Pattern-matching
+        # the string alone would confuse a guard's own wording with any of
+        # those; the raised class does not.
+        GUARD_REFUSAL_KINDS = %w[Hecks::Runtime::GivenNotMet Hecks::Runtime::EnsuresNotMet].freeze
+
+        def guard_refusals_are_declared(history)
+          bluebooks = history.fetch(:bluebooks)
+
+          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])
+
+            "#{refusal[:verb]} refused — #{match[2].inspect} — but #{command.hecks_name} declares no given " \
+              "or ensures with that description (it declares #{declared.inspect})"
+          end
+
+          offenders.empty? || offenders.join("; ")
+        end
+
+        # A DECLARED PROCESS MANAGER'S OWN COMMAND — `command.hecks_name`,
+        # or an entity's own if the verb's second component is itself
+        # dotted (`Aggregate.Entity.Command`, the same two shapes
+        # `Dispatcher#dispatch` itself branches on). Shared by the guard
+        # property above and available for anything else that needs to go
+        # from a replayed verb back to its declaration.
+        #
+        # RESOLVED AGAINST `bluebooks` (the FULL map, `history[:bluebooks]`
+        # — every loaded domain, keyed by name), never a single assumed
+        # bluebook: a verb names its OWN domain (`Naming.split_verb`'s
+        # first element), and that domain is not always the one Replay
+        # happens to expose as `history[:bluebook]`. A fuzz run against
+        # `lib/hecks/grammar` (Expression + Translation, in load
+        # order) found this the hard way — every `Translation::Map.Seal`
+        # refusal read as "no declared command resolves that verb" purely
+        # because `history[:bluebook]` was Expression, not Translation; the
+        # refusal was real, this property's own domain resolution was not.
+        # A DELEGATING DOOR REFUSES WITH ITS TARGET'S OWN WORDS. `delegates_to`
+        # (CommandBuilder#delegates_to_impl) hands the whole dispatch to one
+        # entity command, and that command's given is what refuses — raised
+        # back through the door, in the door's name (chess: `Game.MoveKnight
+        # refused — "it is that color's turn"`, a given Knight.Move declares
+        # and MoveKnight, a pure passthrough, never could). Read the door's
+        # own guards first, then every delegation target's; an offence is
+        # only a description NEITHER declares. Found live mining chess's
+        # history: every refused move through a door read as undeclared.
+        def effective_guard_descriptions(bluebooks, verb, command)
+          own = command.guard_descriptions
+          delegated = command.mutations.select { |m| m.op == :delegate }.flat_map do |delegation|
+            domain, aggregate_name, = Naming.split_verb(verb)
+            target = command_for_verb(bluebooks, "#{domain}::#{aggregate_name}.#{delegation.target}")
+            target ? target.guard_descriptions : []
+          end
+          own + delegated
+        end
+
+        def command_for_verb(bluebooks, verb)
+          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)
+          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
+        end
+
+        # `guard_refusals_are_declared`'s OWN OPPOSITE DIRECTION. That
+        # property is passive and one-directional — for a refusal that
+        # ALREADY HAPPENED, is the quoted text real declared text? It says
+        # nothing about a guard that should have refused and silently did
+        # not — a call site that stopped calling enforce_givens/enforce_
+        # lifecycle_guard would never appear in history[:refusals] at all,
+        # invisible to that property by construction.
+        #
+        # This one calls Admissibility#enforce_givens (which itself folds
+        # in #enforce_lifecycle_guard whenever `declaring:` is passed)
+        # DIRECTLY, against Replay's own pre-dispatch snapshot
+        # (history[:guard_checks], one bounded, additive extension — see
+        # that file's own comment at the capture site) — an independent
+        # recomputation, not grading production against itself, the same
+        # "two engines, compared" shape query_answers_match_reference and
+        # the fan-out oracle already establish. `recomputed_refused`
+        # (Replay's own call, made live, before this step's real dispatch
+        # could mutate anything a cross-aggregate given dereferences) is
+        # compared against `actual_refused` (GivenNotMet/LifecycleRefused
+        # specifically — Replay's own comment on GUARD_REFUSAL_CLASSES
+        # explains why ANY other refusal class, or an outright success,
+        # both count as "the guard did not fire," since enforce_givens
+        # runs FIRST in DISPATCH_ORDER).
+        #
+        # Aggregate#preconditions closes for free alongside this — a
+        # no-block `given` reference (CommandBuilder#given) pushes the
+        # SAME Given struct object `enforce_givens` already iterates
+        # command.givens for, so there is no separate runtime path a
+        # property could exercise beyond what this already reaches.
+        # Entity#preconditions closes the identical way, one level down
+        # (ADR 0028) — a piece's own bare `given` reference pushes the
+        # SAME Given struct onto ITS OWN referencing command's givens,
+        # so LedgerEntry's own Amend/Reverse (banking) already exercise
+        # this through the exact mechanism above, no separate path.
+        #
+        # Real targets: Account.Debit/CloseAccount (`from:` guards),
+        # Credit/Debit (the named-once `given("customer is active")`
+        # precondition) — FreezeAccount deliberately references the
+        # DIFFERENT named precondition `"customer is not closed"` instead
+        # (a suspended customer must still be freezable), so it is not a
+        # `"customer is active"` example, just the same MECHANISM.
+        def lifecycle_guard_and_given_violations_are_refused(history)
+          offenders = history.fetch(:guard_checks).filter_map do |check|
+            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'}"
+          end
+
+          offenders.empty? || offenders.join("; ")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,351 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Stored-record, saga-rehydration, fan-out, and read-model-aggregation
+      # properties: every stored record still satisfies its own declared
+      # invariants, a saga rehydrates cleanly from a checkpoint, a policy's
+      # own for_each/where fans out exactly once per matching row, and a
+      # read model's count/median/group_by answers match an independent
+      # recomputation.
+
+      # Holds stored_records_satisfy_declared_invariants, sagas_rehydrate_cleanly,
+      # fanout_dispatches_once_per_matching_row, aggregation_matches_recompute,
+      # and group_by_matches_recompute, plus the recomputation helpers
+      # (#check_piece_invariants, #eligible_rows, #nest_rows,
+      # #recompute_median) each leans on.
+      module InvariantsAndAggregation
+        # EVERY STORED RECORD STILL SATISFIES ITS OWN AGGREGATE'S DECLARED
+        # INVARIANTS — Admissibility#enforce_invariants (command_rules/
+        # admissibility.rb) checks these AFTER every command's mutations,
+        # BEFORE save, the same point `ensures` is checked. Nothing until
+        # now re-checked a record AFTER a whole replay finished, independent
+        # of whichever call site was supposed to have refused a violation
+        # in the first place — a record failing its own declared invariant
+        # here is proof a violating write landed anyway: the call site
+        # stopped calling enforce_invariants, or some other path (a
+        # translation, a backfill) wrote around it entirely.
+        #
+        # `history[:instances]` entries are already plain, symbol-keyed
+        # state Hashes (Replay.call's own `record.state`) — called against
+        # Evaluator.call the SAME way ValueObject::Builder#build already
+        # does for a VO's own invariants (value/coercion.rb), no GuardState
+        # wrapper needed the way enforce_invariants' own LIVE call uses one
+        # (GuardState exists for `parent.`/projected-field dereferencing
+        # mid-dispatch; a stored record's own scalar fields need none of
+        # that to re-check a same-aggregate invariant against itself).
+        #
+        # Real target: Account's own `invariant("the balance never goes
+        # negative") { balance.cents >= 0 }`.
+        #
+        # Entity#invariants (round 7) closes here too, not for free —
+        # `stored_records_satisfy_declared_invariants` only ever checked
+        # the AGGREGATE's own flat state; a piece's own invariant is
+        # checked against every ELEMENT of a `list_of` field, a genuinely
+        # different walk `check_piece_invariants` below makes,
+        # independently of `Admissibility#check_entity_invariants` (the
+        # live enforcement path this property exists to catch drifting
+        # from) — same reasoning `stored_records_satisfy_declared_
+        # invariants`' own top-level check already applies one level up.
+        #
+        # Real target: SafeDepositBox's own Visit — `invariant("a written
+        # note is not blank") { !note || !note.text.to_s.empty? }`.
+        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.empty? || offenders.join("; ")
+        end
+
+        # A PIECE'S OWN INVARIANT, checked against every element a
+        # `list_of` field holds — the SAME lookup `Admissibility#
+        # check_entity_invariants` makes (`owner.attributes.find { |a|
+        # a.list? && a.type.to_s == entity.hecks_name }`), independently
+        # reapplied here against a STORED record's own 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 CHECKPOINT SURVIVES BEING WRITTEN AND READ
+        # BACK — the durability contract `SagaInterpreter#checkpoint` makes
+        # (`state:` plus a `deep_copy`d `memory:`, handed to whatever
+        # adapter answers `save_saga`) and `Registry#rehydrate_sagas!`
+        # promises to restore on the next boot (`each_saga` yielding
+        # `[pm, correlation, state, memory]` back into `saga_instances`).
+        # `Replay` captures the LIVE store already materialised the same
+        # way `checkpoint` itself does (`Value.materialize`, not raw
+        # `Runtime::Value`s — see its own comment); this property pushes
+        # that captured memory through the SAME `JSON.generate` then
+        # `JSON.parse(symbolize_names: true)` round-trip `checkpoint`'s own
+        # `deep_copy` performs (mirrored here rather than called — a
+        # private instance method with no registry to hand it) and checks
+        # it comes back byte-identical. A memory holding anything that
+        # round-trip cannot carry faithfully — a bare Symbol leaf, a
+        # non-JSON type a future field introduces — is corruption the
+        # durable path would introduce on a REAL restart, caught here
+        # without needing one.
+        #
+        # `declares_state?` (Behaviour::ProcessManager) is the other half:
+        # a live or rehydrated instance sitting in a state the procedure
+        # never declares is the saga-durability twin of
+        # `lifecycle_values_are_declared` above.
+        def sagas_rehydrate_cleanly(history)
+          bluebook = history.fetch(:bluebook)
+          process_managers = 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 = []
+
+              problems << "holds state #{instance[:state].inspect}, which #{pm_name} never declares" \
+                if pm && !pm.declares_state?(instance[:state])
+
+              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
+
+              next if problems.empty?
+
+              "#{pm_name}##{correlation.inspect}: #{problems.join(' and ')}"
+            end
+          end
+
+          offenders.empty? || offenders.join("; ")
+        end
+
+        # A `for_each` POLICY DISPATCHES EXACTLY ONCE PER ROW ITS DECLARED
+        # QUERY ANSWERS — never once for the triggering event regardless of
+        # row count, never skipping a matched row, never firing on a row a
+        # concurrent mutation only made match AFTER the fact. `Replay`
+        # computes the expected row-id set INDEPENDENTLY, at the same
+        # instant the real dispatch runs (`Replay.expected_fan_out_rows`,
+        # the query oracle's own shape aimed at fan-out: two engines
+        # compared, never one graded against itself), and records it
+        # beside what the reaction log actually shows. `expected_row_ids`
+        # is `nil`, not `[]`, when `policy.where` did not hold — no
+        # dispatch is the claim then, not "dispatched to zero rows," and a
+        # policy that dispatched anyway despite a failing guard is as real
+        # a finding as a row it skipped.
+        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?
+
+              next "#{finding[:policy]} on #{finding[:on]}: where did not hold, but dispatched to #{actual.inspect}"
+            end
+
+            next if actual == expected
+
+            "#{finding[:policy]} on #{finding[:on]}: for_each answered #{expected.inspect}, " \
+              "but the reaction log shows dispatches to #{actual.inspect}"
+          end
+
+          offenders.empty? || offenders.join("; ")
+        end
+
+        # A `count`/`median` REPORT'S REDUCED SCALAR MATCHES THE SAME
+        # REDUCTION DONE INDEPENDENTLY, over the SAME eligible rows —
+        # `ReadModelInterpreter#project`'s own FK-join (root first, then
+        # each many-side head matched against it) and `#median` (odd →
+        # the true middle, even → the average of the two middles as a
+        # Float, empty → `nil`; `count` is the filtered length, empty →
+        # `0`), reproduced here in plain Ruby against `history[:instances]`
+        # rather than a live registry — `FieldPath.dig` +
+        # `Ports::Query::InMemory.comparable`/`.holds?` are the SAME two
+        # calls the interpreter itself makes to read a field and judge a
+        # `where`, called here rather than re-derived, so this oracle
+        # cannot drift from what "read a field" or "a clause holds" mean
+        # without the interpreter drifting the identical way.
+        #
+        # Only a report whose `:query` is answered by the SAME bluebook
+        # `history[:bluebook]` carries (the bare `Domain.report_name`
+        # form, `domain == bluebook.name`) is checked — the same "only
+        # what we have the grammar for" scope `lifecycle_values_are_declared`
+        # already takes for a multi-domain replay.
+        # See the comment above: a closed chain of eligibility guards
+        # ("only a report answered by this bluebook, only a count/median
+        # report, only one with a reduced many-side head") each gating the
+        # next, ending in one independent recomputation compared against
+        # the live answer. The guards are what make this oracle SCOPED
+        # correctly, not incidental complexity — narrower than "every
+        # branch reads as its own precondition."
+        # 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 && (model.count? || model.median_field)
+
+            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 = model.count? ? rows.length : recompute_median(rows, model.median_field)
+            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.empty? || offenders.join("; ")
+        end
+
+        # `aggregation_matches_recompute`'s own shape, extended from
+        # reducing a many-side head to a scalar (count/median) to NESTING
+        # it — `ReadModelInterpreter#group_by_target`/`#nest`, reproduced
+        # here in plain Ruby against `history[:instances]` the same way
+        # `eligible_rows` already reproduces the FK-join and `where`
+        # narrowing count/median share. `Value.materialize_unwrapped` is
+        # the SAME call `#project` makes before nesting (a single-field
+        # value object recurses to its bare scalar — a real grouping key
+        # has to BE one) — called here rather than re-derived, so this
+        # oracle cannot drift from what "the group key" means without the
+        # interpreter drifting the identical way.
+        #
+        # Real target: AccountsByKind (`group_by :kind, :number`,
+        # rootless — always generator-eligible with `{}` args).
+        # Same closed eligibility-guard chain as aggregation_matches_
+        # recompute just above (see its own comment) — group_by in place
+        # of count/median, nest_rows in place of recompute_median.
+        # rubocop:disable-next Metrics/CyclomaticComplexity
+        # rubocop:disable-next Metrics/PerceivedComplexity
+        def group_by_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&.group_by&.any?
+
+            grouped_head = model.aggregate_heads.find { |head| head[:many] }
+            next unless grouped_head
+
+            rows = eligible_rows(bluebook, asked.fetch(:instances_at), domain, model, grouped_head, asked[:args] || {})
+            materialized = rows.map { |state| Runtime::Value.materialize_unwrapped(state) }
+            expected = nest_rows(materialized, model.group_by_fields)
+            actual = asked[:rows]&.first&.dig(grouped_head[:as])
+            next if actual == expected
+
+            "#{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
+
+          offenders.empty? || offenders.join("; ")
+        end
+
+        # `ReadModelInterpreter#nest`, byte for byte: one level of nesting
+        # per `group_by` field in declared order, leaf is the row with
+        # every grouped field stripped (already spent, as the keys that
+        # reached it).
+        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 } }
+            rest.empty? ? stripped.first : nest_rows(stripped, rest)
+          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 it has one; a rootless report has
+        # none to match) exactly the way `ReadModelInterpreter#reference_fields`
+        # finds the matching attribute, then narrowed by the report's own
+        # `where` clauses via the SAME `InMemory.holds?` the interpreter's
+        # `execute` calls.
+        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 `record.to_h` (`@state.merge(id:
+          # @id)`) every live head row carries — count/median never read
+          # it, but group_by_matches_recompute's own independent nesting
+          # does, the same way ReadModelInterpreter#row(record) = record.
+          # to_h does for the live path it's checking against.
+          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 byte
+        # for byte: odd count → the true middle value, sorted; even count
+        # → the average of the two middle values, as a Float; empty → nil,
+        # never zero, so a caller cannot mistake "nothing to average" for
+        # "averaged to 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?
+
+          middle = values.length / 2
+          values.length.odd? ? values[middle] : (values[middle - 1] + values[middle]) / 2.0
+        end
+      end
+    end
+  end
+end