hecks 3.5.0 → 3.7.0

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

@@ -0,0 +1,94 @@
+require_relative "checks"
+
+module Hecks
+  module Fuzzing
+    module Mutation
+      # How one mutant fared.
+      #
+      # @!attribute [r] site
+      #   @return [Site] what was changed
+      # @!attribute [r] status
+      #   @return [Symbol] `:killed`, `:survived`, `:unreached` or `:invalid`
+      # @!attribute [r] by
+      #   @return [String, nil] what killed it (`property: <name>`, `crash: <class>`, `corpus: ...`,
+      #     `behavior: ...`), or why it is invalid
+      Outcome = Struct.new(:site, :status, :by, keyword_init: true)
+
+      # Replays one mutant and says which check, if any, noticed.
+      #
+      # The trials run in order and stop at the first that fails. Each answers whether it killed the
+      # mutant and whether the mutant behaved differently from the original under it; a mutant that
+      # differed everywhere it was looked at and was never killed survived.
+      class Judge
+        TRIALS = %i[sequence_trial corpus_trial behavior_trial].freeze
+
+        # @param site [Site] what was changed
+        # @param copy [String] the mutated copy of the domain
+        # @param plan [Plan] what to replay
+        # @param baseline [Hash] what `Checks.baseline` answered for the unmutated domain
+        # @return [Outcome] the verdict
+        def self.call(site, copy, plan, baseline) = new(site, copy, plan, baseline).call
+
+        def initialize(site, copy, plan, baseline)
+          @site = site
+          @copy = copy
+          @plan = plan
+          @baseline = baseline
+        end
+
+        # @return [Outcome] invalid when it does not boot, killed by the first failing trial,
+        #   otherwise survived or unreached by whether anything differed
+        def call
+          reason = Checks.boot_failure(@copy)
+          return outcome(:invalid, reason) if reason
+
+          run_trials
+        rescue StandardError, ScriptError => e
+          outcome(:killed, "crash: #{e.class}")
+        end
+
+        private
+
+        def run_trials
+          differed = false
+          TRIALS.each do |trial|
+            killer, changed = send(trial)
+            return outcome(:killed, killer) if killer
+
+            differed ||= changed
+          end
+          outcome(differed ? :survived : :unreached)
+        end
+
+        def outcome(status, by = nil) = Outcome.new(site: @site, status: status, by: by)
+
+        def sequence_trial
+          differed = false
+          @plan.sequences.each_with_index do |steps, index|
+            history = Replay.call(@copy, steps)
+            broken = Checks.property_failure(history)
+            return [broken, true] if broken
+
+            differed ||= Observation.of(history) != @baseline[:sequences][index]
+          end
+          [nil, differed]
+        end
+
+        def corpus_trial
+          return [nil, false] unless @plan.corpus
+
+          report = Checks.corpus_report(@copy, @plan.corpus)
+          unmet = Checks.unmet_expectation(@plan.corpus, report)
+          return ["corpus: #{unmet}", true] if unmet
+
+          [nil, Observation.of(report) != @baseline[:corpus]]
+        end
+
+        def behavior_trial
+          failing = (Checks.failing_behaviors(@copy) - @baseline[:failing_behaviors]).first
+          [failing && "behavior: #{failing}", !failing.nil?]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+require "json"
+
+module Hecks
+  module Fuzzing
+    module Mutation
+      # A history or report reduced to plain values, so two runs compare equal when they did the
+      # same thing and differ when they did not.
+      module Observation
+        PARTS = %i[instances events refusals reactions sagas queries].freeze
+        PLAIN = [String, Numeric, true, false, nil].freeze
+
+        module_function
+
+        # @param history [Hash] a replay's history, or a `hecks run` report
+        # @return [String] canonical JSON of its observable parts
+        def of(history)
+          JSON.generate(plain(history.slice(*PARTS)))
+        end
+
+        # @return [Object] the value as hashes, arrays, strings, numbers and booleans only
+        def plain(value)
+          case value
+          when Hash then value.sort_by { |key, _| key.to_s }.to_h { |key, item| [key.to_s, plain(item)] }
+          when Array then value.map { |item| plain(item) }
+          when *PLAIN then value
+          else opaque(value)
+          end
+        end
+
+        # An object that is not plain data: its own hash form when it has one, else its text with
+        # the address that would differ between runs taken out.
+        def opaque(value)
+          value.respond_to?(:to_h) ? plain(value.to_h) : value.to_s.gsub(/0x\h+/, "0x")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+require_relative "site"
+require_relative "source_map"
+require_relative "finders"
+
+module Hecks
+  module Fuzzing
+    module Mutation
+      # Finds every site a mutation operator applies to in a bluebook's source.
+      #
+      # Each operator is a small change a reviewer would call a plausible slip: a rule dropped,
+      # a comparison off by one, a guard loosened, a handler forgotten. A site is a candidate
+      # only; the mutant it makes may not boot, and `Run` discards one that does not.
+      module Operators
+        # What each operator does, in the words a report uses.
+        CATALOG = {
+          drop_given:           "removes a `given` guard",
+          drop_invariant:       "removes an `invariant`",
+          flip_comparison:      "moves a comparison one step (`>=` to `>`, `<` to `<=`, `==` to `!=`)",
+          flip_query_bound:     "swaps a query's `lt` and `gt` bound",
+          drop_pattern:         "removes an attribute's `pattern:`",
+          drop_one_of:          "removes an attribute's `one_of:` closed set",
+          drop_sets:            "removes a `sets` line, so the command no longer records that field",
+          drop_from_guard:      "removes a `from:` lifecycle guard",
+          retarget_transition:  "points a lifecycle transition at a different state",
+          drop_policy:          "removes a whole `policy`",
+          drop_saga_transition: "removes a `process_manager` transition and its handler",
+          drop_saga_dispatch:   "removes a `dispatch` a `process_manager` handler makes",
+          swap_emits:           "makes a command emit a different event of the same file"
+        }.freeze
+
+        module_function
+
+        # @param files [Hash{String => String}] bluebook source by path, relative to the domain
+        #   directory
+        # @return [Array<Site>] every site of every operator, in file and line order
+        def sites(files)
+          files.sort.flat_map { |file, source| sites_in(SourceMap.new(file, source.lines)) }
+        end
+
+        # @param map [SourceMap] one bluebook
+        # @return [Array<Site>] its sites
+        def sites_in(map)
+          map.lines.each_index.flat_map do |index|
+            Finders::ALL.flat_map { |finder| finder.at(map, index) }.map do |change|
+              Site.new(file: map.file, line: index + 1, original: map.lines[index], **change)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -17,13 +17,13 @@ module Hecks
       # @param left [Symbol] an `IsolatedBoot` adapter: `:memory`, `:sqlite`, `:postgres`,
       #   `:postgres_era`
       # @param right [Symbol] the second adapter, same set as `left`
-      # @param database [String, nil] required when either side is `:postgres_era`
-      # @param schema [String, nil] required when either side is `:postgres_era`
+      # @param storage [Hash] connection settings `Replay.call` takes, passed to both sides:
+      #   `database:` and `schema:` (strings, required when either side is `:postgres_era`)
       # @return [Array<Hash>] entries `{field: String, left => Object, right => Object}`,
       #   keyed by the adapter symbols; empty if both sides agree
-      def diff(domain_path, steps, left: :memory, right: :postgres_era, database: nil, schema: nil)
-        left_result  = Replay.call(domain_path, steps, adapter: left, database: database, schema: schema)
-        right_result = Replay.call(domain_path, steps, adapter: right, database: database, schema: schema)
+      def diff(domain_path, steps, left: :memory, right: :postgres_era, **storage)
+        left_result  = Replay.call(domain_path, steps, adapter: left, **storage)
+        right_result = Replay.call(domain_path, steps, adapter: right, **storage)
 
         divergences = []
         divergences.concat(diff_instances(left_result, right_result, left, right))

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

@@ -0,0 +1,121 @@
+module Hecks
+  module Fuzzing
+    module Properties
+      # Independent recomputations of read-model reductions and `group_by` nestings, for
+      # `InvariantsAndAggregation` to compare against what a query actually answered.
+      module AggregationRecompute
+        # The read model a recorded ask named, when it belongs to `bluebook`.
+        def asked_read_model(bluebook, asked)
+          domain, name = asked[:query].to_s.split(".", 2)
+          bluebook.read_model(name) if name && domain == bluebook.name
+        end
+
+        # The head a read model reduces or groups: the one declared `many`.
+        def many_head(model) = model.aggregate_heads.find { |head| head[:many] }
+
+        # 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
+
+          recompute_extremum_or_flag(model, rows)
+        end
+
+        # The `min`, `max`, `percentile`, `any` and `all` folds of `recompute_reduction`.
+        def recompute_extremum_or_flag(model, rows)
+          return recompute_values(rows, model.min_field).min if model.min_field
+          return recompute_values(rows, model.max_field).max if model.max_field
+
+          recompute_percentile_or_flag(model, rows)
+        end
+
+        # The `percentile`, `any` and `all` folds of `recompute_reduction`.
+        def recompute_percentile_or_flag(model, rows)
+          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
+
+          recompute_values(rows, model.all_field).all?
+        end
+
+        def recompute_values(rows, field)
+          rows.map { |state| comparable_field(state, field) }.compact
+        end
+
+        # A field's value as the interpreter itself compares it.
+        def comparable_field(state, field)
+          Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(state, field))
+        end
+
+        def recompute_avg(rows, field)
+          values = recompute_values(rows, field)
+          values.empty? ? nil : values.sum.to_f / values.length
+        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?
+
+          interpolate(values, at * (values.length - 1))
+        end
+
+        def interpolate(values, position)
+          lower = position.floor
+          fraction = position - lower
+          fraction.zero? ? values[lower] : values[lower] + (fraction * (values[lower + 1] - values[lower]))
+        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| comparable_field(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
+
+        # 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, model, reduced_head, args)
+          prefix = "#{bluebook.name}::#{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) }
+          rows = rows_for_reference(rows, bluebook.aggregate(reduced_head[:aggregate]), model, args) if model.reference_target
+
+          rows.select { |state| satisfies_wheres?(model, state, args) }
+        end
+
+        # The rows whose foreign key holds the root reference the ask named.
+        def rows_for_reference(rows, aggregate, model, args)
+          reference_id = args[model.reference_name].to_s
+          fk_fields = foreign_key_fields(aggregate, model)
+          rows.select { |state| fk_fields.any? { |field| state[field].to_s == reference_id } }
+        end
+
+        # The names of `aggregate`'s attributes referencing the read model's root.
+        def foreign_key_fields(aggregate, model)
+          aggregate.attributes.select do |attribute|
+            attribute.reference? && attribute.type.target_name == model.reference_target.to_s
+          end.map(&:name)
+        end
+
+        def satisfies_wheres?(model, state, args)
+          model.wheres.all? do |clause|
+            Ports::Query::InMemory.holds?(clause, comparable_field(state, clause.field), args)
+          end
+        end
+      end
+    end
+  end
+end