hecks 3.6.0 → 3.7.0

data/lib/hecks/fuzzing/mutation/report.rb

@@ -0,0 +1,78 @@
+module Hecks
+  module Fuzzing
+    module Mutation
+      # What a mutation run tried and how each mutant ended.
+      #
+      # The score is killed mutants over killed plus survived: the share of behavior-changing
+      # mutants the checks caught. Unreached and invalid mutants say nothing about the checks, so
+      # they stay out of it.
+      class Report
+        # What the run was, for the report's heading.
+        #
+        # @!attribute [r] domain
+        #   @return [String] the domain's name
+        # @!attribute [r] seed
+        #   @return [Integer] the run's seed
+        # @!attribute [r] available
+        #   @return [Integer] how many sites the operators found in all
+        # @!attribute [r] sequences
+        #   @return [Integer] how many generated sequences each mutant was replayed against
+        # @!attribute [r] corpus
+        #   @return [Boolean] whether a corpus script was replayed too
+        Facts = Struct.new(:domain, :seed, :available, :sequences, :corpus)
+
+        SURVIVED = "SURVIVED — behavior changed and no property, corpus expectation or behaviors test failed:".freeze
+        UNREACHED = "UNREACHED — no sequence told these apart from the original (equivalent, or never exercised):".freeze
+
+        attr_reader :facts, :verdicts
+
+        # @param facts [Facts] what the run was
+        # @param verdicts [Array<Outcome>] one per mutant tried
+        def initialize(facts, verdicts)
+          @facts = facts
+          @verdicts = verdicts
+        end
+
+        %i[killed survived unreached invalid].each do |status|
+          define_method(status) { verdicts.select { |outcome| outcome.status == status } }
+        end
+
+        # @return [Float, nil] killed / (killed + survived), nil when no mutant changed behavior
+        def score
+          judged = killed.size + survived.size
+          judged.zero? ? nil : killed.size.fdiv(judged)
+        end
+
+        # @param minimum [Float] the lowest score that still passes
+        # @return [Boolean] whether the score is at least `minimum`; a run with nothing judged
+        #   passes
+        def passes?(minimum) = score.nil? || score >= minimum
+
+        # @return [String] the report as the command prints it
+        def to_s
+          [title, tally, *section(SURVIVED, survived), *section(UNREACHED, unreached)].join("\n")
+        end
+
+        private
+
+        def title
+          score_text = score ? format("%.0f%%", score * 100) : "n/a"
+          "mutation #{facts.domain} (seed #{facts.seed}): #{verdicts.size} of #{facts.available} mutants tried " \
+            "against #{facts.sequences} sequence(s)#{" and the corpus script" if facts.corpus} — score #{score_text}"
+        end
+
+        def tally
+          "  killed #{killed.size}, survived #{survived.size}, unreached #{unreached.size}, invalid #{invalid.size}"
+        end
+
+        def section(heading, outcomes)
+          outcomes.empty? ? [] : ["", heading, *outcomes.map { |outcome| describe(outcome.site) }]
+        end
+
+        def describe(site)
+          "  #{site.id}  #{Operators::CATALOG.fetch(site.operator)}\n    was: #{site.original.strip}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/mutation/run.rb

@@ -0,0 +1,99 @@
+require "fileutils"
+require "json"
+require "tmpdir"
+require_relative "operators"
+require_relative "judge"
+require_relative "selection"
+require_relative "report"
+
+module Hecks
+  module Fuzzing
+    module Mutation
+      # Mutation testing of a domain's own checks: makes each small change `Operators` finds to a
+      # copy of the domain, replays the same generated sequences, the domain's corpus script (when
+      # it has one) and its `.behaviors` tests against the copy, and asks whether any check noticed.
+      #
+      # A mutant is killed when a fuzz property fails, the replay crashes, a corpus expectation
+      # goes unmet or a behaviors test fails. It survives when its behavior differs from the
+      # unmutated domain's and nothing failed: the checks have a hole there. It is unreached when
+      # no sequence told it apart from the original, which is either an equivalent change or a
+      # part of the domain the generator never gets to. A mutant that does not boot is invalid and
+      # counts toward no score.
+      #
+      # Deterministic: the sequences and the choice of mutants both come from `seed`.
+      class Run
+        # The checkout this file lives in, where a domain's corpus script is looked for.
+        ROOT = File.expand_path("../../../..", __dir__)
+
+        # The knobs of a run: `seed` draws the sequences and the choice of mutants; `budget` caps
+        # the mutants tried; `seeds` and `steps` size the generated sequences each mutant is
+        # replayed against; `corpus` is a script to replay too (found by the domain's name when
+        # nil); `operators` restricts the run to those operators when given.
+        Settings = Struct.new(:seed, :budget, :seeds, :steps, :corpus, :operators, keyword_init: true)
+
+        DEFAULTS = { seed: 1, budget: 25, seeds: 3, steps: 30, corpus: nil, operators: nil }.freeze
+
+        # @param domain [String] the domain directory
+        # @param options [Hash] any of `Settings`' members
+        # @return [Report] what was tried and how each mutant ended
+        def self.call(domain, **) = new(domain, Settings.new(**DEFAULTS, **)).call
+
+        def initialize(domain, settings)
+          @domain = domain.chomp("/")
+          @settings = settings
+        end
+
+        # @return [Report] the mutants tried, each with its verdict
+        def call
+          plan = Plan.new(generate_sequences, corpus_script)
+          baseline = Checks.baseline(@domain, plan)
+          sites = Operators.sites(bluebook_sources)
+          verdicts = chosen(sites).map { |site| judge(site, plan, baseline) }
+          Report.new(facts(sites.size, plan), verdicts)
+        end
+
+        private
+
+        def facts(available, plan)
+          Report::Facts.new(File.basename(@domain), @settings.seed, available, plan.sequences.size, !plan.corpus.nil?)
+        end
+
+        def chosen(sites)
+          Selection.pick(sites, budget: @settings.budget, seed: @settings.seed, operators: @settings.operators)
+        end
+
+        # The same sequences for every mutant, generated against the unmutated domain so each is
+        # valid there and any difference is the mutation's.
+        def generate_sequences
+          Array.new(@settings.seeds) do |index|
+            SequenceGenerator.generate(@domain, seed: @settings.seed + index, steps: @settings.steps,
+                                                adversarial: index.odd? ? 0.3 : 0.0)
+          end
+        end
+
+        def judge(site, plan, baseline)
+          Dir.mktmpdir("hecks-mutant") do |tmp|
+            copy = File.join(tmp, File.basename(@domain))
+            FileUtils.cp_r(@domain, copy)
+            path = File.join(copy, site.file)
+            File.write(path, site.apply(File.readlines(path)).join)
+            Judge.call(site, copy, plan, baseline)
+          end
+        end
+
+        # @return [Hash{String => String}] each bluebook of the domain by path relative to it
+        def bluebook_sources
+          Dir.glob(File.join(@domain, "**", "*.bluebook")).to_h do |path|
+            [path.delete_prefix("#{@domain}/"), File.read(path)]
+          end
+        end
+
+        # The parsed corpus script: the one asked for, else the one of this domain's name.
+        def corpus_script
+          path = @settings.corpus || File.join(ROOT, "spec", "corpus", "#{File.basename(@domain)}.json")
+          File.file?(path) ? JSON.parse(File.read(path)) : nil
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/mutation/selection.rb

@@ -0,0 +1,32 @@
+module Hecks
+  module Fuzzing
+    module Mutation
+      # Chooses which sites to try within a budget: every operator gets a turn before any gets a
+      # second, each in a seeded shuffle, so a small budget still samples all of them instead of
+      # exhausting the first.
+      module Selection
+        module_function
+
+        # @param sites [Array<Site>] every site found
+        # @param budget [Integer] how many to take at most
+        # @param seed [Integer] draws the shuffle
+        # @param operators [Array<Symbol>, nil] restricts the choice to these operators
+        # @return [Array<Site>] the sites to try, repeatable for one seed
+        def pick(sites, budget:, seed:, operators: nil)
+          sites = sites.select { |site| operators.include?(site.operator) } if operators
+          rng = Random.new(seed)
+          queues = sites.group_by(&:operator).sort_by { |operator, _| operator.to_s }
+                        .map { |_, group| group.shuffle(random: rng) }
+          deal(queues, budget)
+        end
+
+        # Takes one from each queue in turn until the budget is spent or they are empty.
+        def deal(queues, budget)
+          taken = []
+          taken.concat(queues.filter_map(&:shift)) while taken.size < budget && queues.any?(&:any?)
+          taken.first(budget)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/mutation/site.rb

@@ -0,0 +1,21 @@
+module Hecks
+  module Fuzzing
+    module Mutation
+      # One place a small semantic change can be made to a bluebook's source: which `operator`
+      # (a key of `Operators::CATALOG`), in which `file` (relative to the domain directory), at
+      # which `line` (the first it touches, from 1), how many lines it `removed` from there, the
+      # `replacement` lines that stand in their place (none for a pure removal) and the `original`
+      # line, for a report.
+      Site = Struct.new(:operator, :file, :line, :removed, :replacement, :original, keyword_init: true) do
+        # @return [String] the stable name of this mutant, `operator@file:line`
+        def id = "#{operator}@#{file}:#{line}"
+
+        # @param lines [Array<String>] the bluebook's lines, newline-terminated
+        # @return [Array<String>] the lines with this change made
+        def apply(lines)
+          lines.dup.tap { |changed| changed[line - 1, removed] = replacement }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/mutation/source_map.rb

@@ -0,0 +1,59 @@
+module Hecks
+  module Fuzzing
+    module Mutation
+      # What a bluebook's source says about itself, so a finder can ask where a line sits: the block
+      # keyword it is inside, how long the block that starts on it runs, and which lifecycle states
+      # and events the file names.
+      class SourceMap
+        # A line that opens a block, as `policy "X" do` or `command "Y", from: "z" do |a|`.
+        OPENER = /\A(\s*)(\w+)\b.*\bdo\s*(\|[^|]*\|)?\s*\z/
+        TRANSITION = /\A(\s*)transition\s+"(\w+)"\s*=>\s*"([^"]+)"(.*?)\s*\z/
+        EMITS = /\A(\s*)emits\s+(\w+)\s*\z/
+
+        attr_reader :file, :lines
+
+        # @param file [String] the bluebook's path relative to the domain directory
+        # @param lines [Array<String>] its lines, newline-terminated
+        def initialize(file, lines)
+          @file = file
+          @lines = lines
+          @scopes = compute_scopes
+        end
+
+        # @param index [Integer] a line's position, from 0
+        # @return [String, nil] the keyword of the innermost block the line is inside
+        def scope(index) = @scopes[index]
+
+        # @return [Array<String>] every state a `transition` in the file moves to
+        def states
+          @states ||= lines.filter_map { |line| line[TRANSITION, 3] }.uniq
+        end
+
+        # @return [Array<String>] every event name a command in the file emits
+        def emitted
+          @emitted ||= lines.filter_map { |line| line[EMITS, 2] }.uniq
+        end
+
+        # @param index [Integer] the position of the line that opens a block
+        # @return [Integer, nil] the lines from it to its `end`, nil when the block never closes
+        def block_length(index)
+          indent = lines[index][/\A\s*/]
+          close = ((index + 1)...lines.length).find { |at| lines[at].match?(/\A#{indent}end\b/) }
+          close && ((close - index) + 1)
+        end
+
+        private
+
+        def compute_scopes
+          stack = []
+          lines.map do |line|
+            stack.pop while stack.any? && line.match?(/\A#{stack.last[0]}end\b/)
+            inside = stack.last&.last
+            (match = line.match(OPENER)) && stack.push([match[1], match[2]])
+            inside
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/fuzzing/mutation.rb

@@ -0,0 +1,12 @@
+require_relative "../fuzzing"
+require_relative "mutation/run"
+
+module Hecks
+  module Fuzzing
+    # Mutation testing of a domain's own checks: small semantic changes to its bluebooks, each run
+    # past the fuzz properties and the corpus script to see whether anything fails. A mutant nothing
+    # fails on is a hole in the checks. See `Mutation::Run`.
+    module Mutation
+    end
+  end
+end

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

@@ -23,7 +23,10 @@ module Hecks
         :outbox_rows_match_reactions,
         :policy_reactions_follow_declared_wiring,
         :declared_undelivered_policies_stay_undelivered,
-        :references_resolve_to_earlier_records
+        :references_resolve_to_earlier_records,
+        :role_checks_agree_with_grants,
+        :read_model_names_resolve_uniquely,
+        :read_model_heads_compose_from_references
       ].freeze
 
       # Which language feature each property is answerable for — exhaustive of
@@ -69,70 +72,18 @@ module Hecks
         declared_undelivered_policies_stay_undelivered:   %w[Policy#expect_undelivered],
         # An accepted referencing command addressed a record an earlier event created.
         references_resolve_to_earlier_records:            %w[Command#references],
+        # The grants read back through the verb the authorization provider declares in `provides`.
+        role_checks_agree_with_grants:                    %w[Bluebook#provides],
+        read_model_names_resolve_uniquely:                %w[ReadModel#query_name],
+        # Each head's rows recomputed from the references; options apply to targeted heads only.
+        read_model_heads_compose_from_references:         %w[ReadModel#reference_name ReadModel#reference_target
+                                                             ReadModel#aggregate_heads ReadModel#options],
         # No feature string exists for what this reads: an argument's own
         # `relationship` (Argument is a value object, outside the meta-domain
         # walk). Its declaration side, `Query#options`, is already claimed by
         # authorize_scopes_or_refuses.
         commands_respect_tenant_scope:                    []
       }.freeze
-
-      # Features a replay could never observe violated, because construction
-      # makes the violation impossible to produce — not untested, but
-      # unfalsifiable. Each entry names the runtime path that guarantees it;
-      # add one only after reading and confirming that path (mirrors the
-      # discipline spec/fuzzing/meta_domain_coverage_spec.rb's KNOWN_GAPS demands
-      # in the other direction).
-      GUARANTEED_BY_CONSTRUCTION = {
-        "Aggregate#attributes"    => "every field's pattern/closed-set/type passes through Value.build's one coercion " \
-                                     "door (value/coercion.rb#check_patterns, value/admission.rb) before it can exist " \
-                                     "— a stored value that violated its own declared shape was never producible to " \
-                                     "begin with",
-        "Aggregate#value_objects" => "the shape being coerced above — same door, same guarantee",
-        # S17, ADR 0026 — saga_advances_follow_declared_handlers already walks
-        # this list to find event_type/from_state/to_state; same door, same guarantee.
-        "ProcessManager#handlers" => "saga_advances_follow_declared_handlers already walks this list to find " \
-                                     "event_type/from_state/to_state — same door, same guarantee",
-        "Aggregate#identified_by" => "CommandInterpreter's data-driven dispatch order refuses AlreadyExists " \
-                                     "(command_interpreter.rb, command.creates?) for every creating command uniformly, " \
-                                     "before a duplicate id can ever be stored — collision is refused at the door, not " \
-                                     "produced and later caught",
-        "Entity#identified_by"    => "EntityElement.check_entity_collision (runtime/entity_element.rb, moved there " \
-                                     "BUG#145 so both call sites share it) checks Array(current) against every part " \
-                                     "of the entity's own identity before an append can land — MutationApplier#" \
-                                     "entity_element's aggregate-owned call (Workspace.boards, on both branches " \
-                                     "identity arrives by: caller-supplied, or composite) AND EntityElement#" \
-                                     "appended_to_element's entity-owned, nested-one-hop-further call (Board.cards — " \
-                                     "unconditional, no auto-mint branch exists at that depth) — the same " \
-                                     "AlreadyExists refusal Aggregate#identified_by gets above, one or two levels " \
-                                     "down. Auto-minted (aggregate-owned) entities never reach the check " \
-                                     "(current.size + 1 can't repeat unless something remove:s from the list between " \
-                                     "mints, which no real domain does today — see the comment on #entity_element " \
-                                     "itself)",
-        "Command#attributes"      => "command arguments are coerced through the SAME Value.build door as any other " \
-                                     "attribute — an accepted dispatch's own args already passed pattern/admits/invariant checks",
-        "Command#emits"           => "CommandRules::Emission#emit iterates command.emits ITSELF to construct every " \
-                                     "announced Event (command_rules/emission.rb) — there is no other path to emit, so " \
-                                     "a command can never announce a name its own declaration doesn't list",
-        "Query#attributes"        => "query arguments are coerced through the same Value.build door — same guarantee as " \
-                                     "Command#attributes",
-        "Query#returns"           => "every row a port answers is built as the returned value object by Value.build " \
-                                     "(QueryInterpreter#shaped) before it enters the domain — an answer of any other " \
-                                     "shape is refused, so none can be accepted",
-        "Entity#attributes"       => "same coercion door, one level in — an entity's own attributes are Value-typed exactly " \
-                                     "the way an aggregate's are",
-        "ValueObject#attributes"  => "the shape Value.build enforces IS this declaration — the guarantee and the " \
-                                     "feature are the same fact seen from two sides",
-        "ValueObject#invariants"  => "run inside the SAME coercion call (coercion.rb, before construction returns) " \
-                                     "that pattern-checks a VO's fields — a VO whose invariant did not hold could not " \
-                                     "finish being built",
-        "ValueObject#rows"        => "closed-set membership is checked in value/admission.rb, the second half of the same " \
-                                     "one construction door",
-        # S17, ADR 0026 — Member is a genuine entity, so this reads Member#pairs,
-        # not Member#shape. ValueObject#members is the same fact ValueObject#rows
-        # counts, seen from the other side.
-        "ValueObject#members"     => "the members list IS what ValueObject#rows counts — same door, same guarantee",
-        "Member#pairs"            => "one level into ValueObject#rows — same door"
-      }.freeze
     end
   end
 end

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

@@ -0,0 +1,63 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Features a replay could never observe violated, because construction
+      # makes the violation impossible to produce — not untested, but
+      # unfalsifiable. Each entry names the runtime path that guarantees it;
+      # add one only after reading and confirming that path (mirrors the
+      # discipline spec/fuzzing/meta_domain_coverage_spec.rb's KNOWN_GAPS demands
+      # in the other direction).
+      GUARANTEED_BY_CONSTRUCTION = {
+        "Aggregate#attributes"    => "every field's pattern/closed-set/type passes through Value.build's one coercion " \
+                                     "door (value/coercion.rb#check_patterns, value/admission.rb) before it can exist " \
+                                     "— a stored value that violated its own declared shape was never producible to " \
+                                     "begin with",
+        "Aggregate#value_objects" => "the shape being coerced above — same door, same guarantee",
+        # S17, ADR 0026 — saga_advances_follow_declared_handlers already walks
+        # this list to find event_type/from_state/to_state; same door, same guarantee.
+        "ProcessManager#handlers" => "saga_advances_follow_declared_handlers already walks this list to find " \
+                                     "event_type/from_state/to_state — same door, same guarantee",
+        "Aggregate#identified_by" => "CommandInterpreter's data-driven dispatch order refuses AlreadyExists " \
+                                     "(command_interpreter.rb, command.creates?) for every creating command uniformly, " \
+                                     "before a duplicate id can ever be stored — collision is refused at the door, not " \
+                                     "produced and later caught",
+        "Entity#identified_by"    => "EntityElement.check_entity_collision (runtime/entity_element.rb, moved there " \
+                                     "BUG#145 so both call sites share it) checks Array(current) against every part " \
+                                     "of the entity's own identity before an append can land — MutationApplier#" \
+                                     "entity_element's aggregate-owned call (Workspace.boards, on both branches " \
+                                     "identity arrives by: caller-supplied, or composite) AND EntityElement#" \
+                                     "appended_to_element's entity-owned, nested-one-hop-further call (Board.cards — " \
+                                     "unconditional, no auto-mint branch exists at that depth) — the same " \
+                                     "AlreadyExists refusal Aggregate#identified_by gets above, one or two levels " \
+                                     "down. Auto-minted (aggregate-owned) entities never reach the check " \
+                                     "(current.size + 1 can't repeat unless something remove:s from the list between " \
+                                     "mints, which no real domain does today — see the comment on #entity_element " \
+                                     "itself)",
+        "Command#attributes"      => "command arguments are coerced through the SAME Value.build door as any other " \
+                                     "attribute — an accepted dispatch's own args already passed pattern/admits/invariant checks",
+        "Command#emits"           => "CommandRules::Emission#emit iterates command.emits ITSELF to construct every " \
+                                     "announced Event (command_rules/emission.rb) — there is no other path to emit, so " \
+                                     "a command can never announce a name its own declaration doesn't list",
+        "Query#attributes"        => "query arguments are coerced through the same Value.build door — same guarantee as " \
+                                     "Command#attributes",
+        "Query#returns"           => "every row a port answers is built as the returned value object by Value.build " \
+                                     "(QueryInterpreter#shaped) before it enters the domain — an answer of any other " \
+                                     "shape is refused, so none can be accepted",
+        "Entity#attributes"       => "same coercion door, one level in — an entity's own attributes are Value-typed exactly " \
+                                     "the way an aggregate's are",
+        "ValueObject#attributes"  => "the shape Value.build enforces IS this declaration — the guarantee and the " \
+                                     "feature are the same fact seen from two sides",
+        "ValueObject#invariants"  => "run inside the SAME coercion call (coercion.rb, before construction returns) " \
+                                     "that pattern-checks a VO's fields — a VO whose invariant did not hold could not " \
+                                     "finish being built",
+        "ValueObject#rows"        => "closed-set membership is checked in value/admission.rb, the second half of the same " \
+                                     "one construction door",
+        # S17, ADR 0026 — Member is a genuine entity, so this reads Member#pairs,
+        # not Member#shape. ValueObject#members is the same fact ValueObject#rows
+        # counts, seen from the other side.
+        "ValueObject#members"     => "the members list IS what ValueObject#rows counts — same door, same guarantee",
+        "Member#pairs"            => "one level into ValueObject#rows — same door"
+      }.freeze
+    end
+  end
+end

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

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

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

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