karst 0.1.0

data/lib/karst/access/probe_application.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Karst
+  module Access
+    # Builds the smallest Rack endpoint which still gives a controller request
+    # Rails' cookie and session facilities. Calling Rails.application here would
+    # recursively enter every host middleware (including the middleware which
+    # initiated the sweep). RouteSet is the stable Rails dispatch boundary: it
+    # performs recognition and controller dispatch, but has no host middleware.
+    class ProbeApplication
+      class ConstructionError < StandardError; end
+
+      # Supplies the same Rails request environment as Rails::Application
+      # without calling its compiled middleware stack.
+      class Environment
+        attr_reader :host
+
+        def initialize(app, defaults, host)
+          @app = app
+          @defaults = defaults
+          @host = host
+        end
+
+        # Mutates the caller's own env in place (filling in only keys it
+        # doesn't already set -- @defaults never overrides an explicit
+        # incoming value) rather than building a new merged Hash. Downstream
+        # middleware Karst wraps this env with, in particular Warden::Manager
+        # setting env["warden"], must remain visible on the exact env object
+        # ActionDispatch::Integration::Session retains as #request.env after
+        # the call returns -- a fresh copy would silently discard every
+        # mutation the moment this method returned, leaving Karst unable to
+        # find that same Warden proxy again afterward (see WardenAdapter#clear).
+        def call(env)
+          @defaults.each { |key, value| env[key] = value unless env.key?(key) }
+          @app.call(env)
+        end
+      end
+      private_constant :Environment
+
+      class << self
+        def for(application)
+          return application unless rails_application?(application)
+
+          build(application)
+        rescue LoadError, StandardError => e
+          raise ConstructionError,
+                "Karst could not build the Rails probe endpoint; check the application's session store configuration",
+                cause: e
+        end
+
+        private
+
+        def build(application)
+          require_dependencies
+          endpoint = application.routes
+          endpoint = wrap_warden(endpoint)
+          endpoint = ActionDispatch::Flash.new(endpoint)
+          endpoint = session_middleware(application).new(endpoint, **session_options(application))
+          endpoint = ActionDispatch::Cookies.new(endpoint)
+          Environment.new(endpoint, application.env_config, probe_host(application))
+        end
+
+        def require_dependencies
+          require "action_dispatch/middleware/cookies"
+          require "action_dispatch/middleware/flash"
+          require "action_dispatch/middleware/session/cookie_store"
+        end
+
+        # Mirrors the host application's own middleware order (Warden::Manager
+        # sits directly in front of the router, inside session/flash/cookies)
+        # so `env["warden"]` exists for Karst::Identity::WardenAdapter -- the
+        # same object a real host request would see. Without this, a Devise
+        # (or otherwise Warden-based) application's probes would fail every
+        # single principal with Karst::Identity::Unavailable, since nothing
+        # else in this deliberately minimal Rack stack ever initializes a
+        # Warden proxy. Reuses Devise's own already-configured Warden::Config
+        # (scope defaults, session serializers, failure app) when Devise is
+        # present, rather than an empty default one, so a probe that reaches
+        # an unauthenticated 401/302 behaves exactly as it would for a real
+        # request instead of raising "No Failure App provided".
+        # Falls back to leaving `endpoint` unwrapped, rather than letting
+        # construction failure abort the whole probe, when Warden::Manager
+        # doesn't behave like the real middleware (for example a bare stand-in
+        # Class with Object's own zero-argument #initialize, as several specs
+        # use to exercise Devise-detection paths where explicit
+        # config.assume_identity/config.assume_browser_identity hooks already
+        # make WardenAdapter -- and so this wrapping -- unnecessary).
+        # Passed through the config block, never as Warden::Manager.new's own
+        # `options` argument: that constructor special-cases an
+        # options[:default_strategies] key by deleting it and re-adding it
+        # via `@config.default_strategies(*default_strategies)`, which
+        # assumes a flat Array of strategy names. Devise's own
+        # warden_config[:default_strategies] is already a Hash keyed by
+        # scope (e.g. {user: [...], admin: [...]}); splatting that Hash
+        # turns each [scope, strategies] pair into a positional argument, so
+        # every scope name (:admin, :user, ...) ends up misfiled into the
+        # :_all strategy list as if it were itself a strategy -- harmless
+        # for a single scope (nothing ever runs real strategies for a
+        # principal Karst just set_user'd into that exact scope), but a
+        # probed principal under one scope hitting a route gated on another
+        # then raises Warden's own "Invalid strategy admin" the moment
+        # multiple Devise models are involved. config.merge! after
+        # construction copies the same Hash in verbatim instead.
+        def wrap_warden(endpoint)
+          return endpoint unless defined?(Warden::Manager)
+
+          Warden::Manager.new(endpoint) { |config| config.merge!(devise_warden_config) }
+        rescue StandardError
+          endpoint
+        end
+
+        # A duplicate, never the live object: Warden::Manager#initialize
+        # destructively deletes :default_strategies from whatever options
+        # Hash it's given, and Devise's own warden_config is the one shared,
+        # mutable object every real host request also authenticates through
+        # -- corrupting it here would silently break the host application's
+        # own Devise authentication after a single Karst probe.
+        #
+        # Devise only populates warden_config (failure_app, scope_defaults,
+        # session serializers) the first time its routes finalize, which
+        # normally has already happened by the time a real /karst request
+        # reaches Sweep (Identity.setup_state/principal_sources already
+        # forced it via Devise.mappings). Calling Devise.mappings here too
+        # makes that a guarantee rather than an incidental ordering, so the
+        # very first sweep of a freshly booted process still gets a complete
+        # config instead of an empty one.
+        def devise_warden_config
+          return {} unless defined?(Devise) && Devise.respond_to?(:warden_config)
+
+          Devise.mappings if Devise.respond_to?(:mappings)
+          Devise.warden_config&.dup || {}
+        end
+
+        def rails_application?(application)
+          application.respond_to?(:routes) && application.respond_to?(:config)
+        end
+
+        def session_middleware(application)
+          application.config.session_store || ActionDispatch::Session::CookieStore
+        end
+
+        def session_options(application)
+          application.config.session_options.to_h
+        end
+
+        def probe_host(application)
+          candidates = [application.routes.default_url_options[:host]]
+          candidates.concat(Array(application.config.hosts).grep(String))
+          if defined?(ActionDispatch::HostAuthorization::ALLOWED_HOSTS_IN_DEVELOPMENT)
+            candidates.concat(ActionDispatch::HostAuthorization::ALLOWED_HOSTS_IN_DEVELOPMENT.grep(String))
+          end
+          candidates.filter_map { |candidate| safe_host(candidate) }.first
+        end
+
+        def safe_host(candidate)
+          host = candidate.to_s.sub(/\A\./, "")
+          return if host.empty? || host.match?(%r{[\s/:]})
+
+          host
+        end
+      end
+    end
+  end
+end

data/lib/karst/access/resource_evidence.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+require_relative "../value"
+require_relative "../identity"
+
+module Karst
+  module Access
+    # Given one exact resource (the specific record a route addresses by id)
+    # and one specific principal (typically the successful outcome from an
+    # Access::Sweep), reports simple, directly observed foreign-key
+    # relationships between those two records. This is evidence, not an
+    # authorization claim: it never states or implies *why* an outcome
+    # occurred, only which foreign-key columns, if any, point from one given
+    # record to the other's id.
+    #
+    # Deliberately narrow, matching the v1 scope this class was built for:
+    # - only foreign-key-shaped columns (ending in "_id") on the two given
+    #   records are ever inspected -- never an arbitrary attribute, so no
+    #   other column value (name, email, token, ...) is ever read or shown;
+    # - only a direct column-value comparison between the two given records,
+    #   never a join, a has_many traversal, or any multi-hop graph walk;
+    # - resource resolution from a route path is attempted only through
+    #   Rails' own route recognition plus its controller-to-model naming
+    #   convention, and only trusted when every step succeeds unambiguously
+    #   (a recognized route with an :id segment, a controller name that
+    #   classifies to a real loaded Active Record class, and a record that
+    #   actually exists for that id). Anything softer -- an unrecognized
+    #   route, a controller with no conventional model, a missing record --
+    #   is reported as a limitation rather than guessed at.
+    # rubocop:disable Metrics/ClassLength
+    class ResourceEvidence
+      class Error < StandardError; end
+
+      # The resource side never gets Identity::PrincipalDescriptor's
+      # configurable display_label hook -- there is no equivalent concept
+      # for "the current route's resource" -- so it gets its own minimal,
+      # equally attribute-free descriptor.
+      ResourceDescriptor = Value.define(:model_name, :id)
+
+      # from_model/from_id is whichever of the resource/principal actually
+      # holds the foreign-key column; to_model/to_id is the other side.
+      Relationship = Value.define(:column, :from_model, :from_id, :to_model, :to_id)
+
+      Result = Value.define(:principal, :resource, :relationships, :observed_status, :observed_redirect,
+                            :limitation) do
+        # Plain-text rendering deliberately kept free of causal wording
+        # ("owns", "is authorized", "grants") -- see class comment above.
+        def to_text
+          lines = [principal.display_label]
+          lines << observed_line if observed_status || observed_redirect
+          lines << "" << "Related state:"
+          lines.concat(related_state_lines)
+          lines.join("\n")
+        end
+
+        private
+
+        def observed_line
+          observed_redirect ? "Observed #{observed_status} → #{observed_redirect}" : "Observed #{observed_status}"
+        end
+
+        def related_state_lines
+          return ["  Unavailable: #{limitation}"] if limitation
+          return [no_relationship_line] if relationships.empty?
+
+          grouped_relationship_lines
+        end
+
+        def no_relationship_line
+          "  No observed foreign-key relationship to #{resource.model_name} ##{resource.id}."
+        end
+
+        def grouped_relationship_lines
+          relationships.group_by { |rel| [rel.from_model, rel.from_id] }.flat_map do |(model, id), grouped|
+            ["#{model} ##{id}"] + grouped.map { |rel| "  #{rel.column} → #{rel.to_model} ##{rel.to_id}" }
+          end
+        end
+      end
+
+      class << self
+        # Resolves the resource, resolves the principal (from a
+        # Sweep::Outcome's PrincipalDescriptor), and reports relationships in
+        # one call. Either resolution step may fail safely -- see
+        # #resolve_resource and #resolve_principal -- in which case the
+        # Result carries a limitation instead of relationships.
+        def for_outcome(outcome:, path:, http_method: "GET", application: nil)
+          resource, resource_limitation = resolve_resource(path: path, http_method: http_method,
+                                                           application: application)
+          principal, principal_limitation = resolve_principal(outcome.principal)
+          limitation = [resource_limitation, principal_limitation].compact.join("; ")
+
+          return unresolved_result(outcome, limitation) if resource.nil? || principal.nil?
+
+          new(resource: resource, principal: principal).call(
+            observed_status: outcome.status, observed_redirect: outcome.redirect
+          )
+        end
+
+        # Attempts to resolve the exact record a route addresses, trusting
+        # only Rails' own route recognition and controller naming
+        # convention, and only when every step is unambiguous. Returns
+        # [record, nil] on success or [nil, reason] when any step is not
+        # reliable -- never a guessed record.
+        def resolve_resource(path:, http_method: "GET", application: nil)
+          app = application || rails_application
+          return [nil, "no Rails application is available to recognize the route"] unless app
+
+          params = recognize(app, path, http_method)
+          return [nil, "the route could not be recognized"] unless params
+
+          id = params[:id]
+          return [nil, "the recognized route has no :id segment addressing one specific resource"] unless id
+
+          find_by_controller(params[:controller], id)
+        end
+
+        # Resolves the actual record behind a Karst::Identity::PrincipalDescriptor
+        # only through the configured principal source. A valid model/id outside
+        # that source is deliberately unresolved.
+        def resolve_principal(descriptor)
+          record = Identity.resolve(model_name: descriptor.model_name, id: descriptor.id)
+          return [nil, "principal is not available from the configured principal source"] unless record
+
+          [record, nil]
+        rescue Identity::Error
+          [nil, "the configured principal source is unavailable"]
+        end
+
+        private
+
+        def rails_application
+          defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+        end
+
+        def find_by_controller(controller, id)
+          klass = active_record_class(controller.to_s.classify)
+          return [nil, "the route's controller does not map to a loaded Active Record model by convention"] unless klass
+
+          record = klass.find_by(klass.primary_key => id)
+          return [nil, "no #{klass.name} record exists for id #{id.inspect}"] unless record
+
+          [record, nil]
+        end
+
+        def unresolved_result(outcome, limitation)
+          Result.new(principal: outcome.principal, resource: nil, relationships: [].freeze,
+                     observed_status: outcome.status, observed_redirect: outcome.redirect,
+                     limitation: limitation.empty? ? "the resource or principal could not be resolved" : limitation)
+        end
+
+        def recognize(app, path, http_method)
+          app.routes.recognize_path(path, method: http_method)
+        rescue StandardError
+          nil
+        end
+
+        def active_record_class(name)
+          klass = name.to_s.safe_constantize
+          return nil unless defined?(ActiveRecord::Base) && klass.is_a?(Class) && klass < ActiveRecord::Base
+
+          klass
+        end
+      end
+
+      def initialize(resource:, principal:)
+        @resource = resource
+        @principal = principal
+      end
+
+      def call(observed_status: nil, observed_redirect: nil)
+        Result.new(
+          principal: Identity.describe(@principal),
+          resource: ResourceDescriptor.new(model_name: model_name(@resource), id: primary_key_value(@resource)),
+          relationships: relationships.freeze,
+          observed_status: observed_status,
+          observed_redirect: observed_redirect,
+          limitation: nil
+        )
+      end
+
+      private
+
+      def relationships
+        foreign_keys_from(@resource, @principal) + foreign_keys_from(@principal, @resource)
+      end
+
+      def foreign_keys_from(source, target)
+        return [] unless active_record?(source) && active_record?(target)
+
+        source.class.columns_hash.values.filter_map { |column| relationship_for(source, target, column) }
+      end
+
+      def relationship_for(source, target, column)
+        return unless foreign_key_column?(source.class, column)
+        return unless targets?(column, target.class)
+
+        value = source.public_send(column.name)
+        return if value.nil? || value != primary_key_value(target)
+
+        Relationship.new(column: column.name, from_model: model_name(source), from_id: primary_key_value(source),
+                         to_model: model_name(target), to_id: primary_key_value(target))
+      end
+
+      def foreign_key_column?(klass, column)
+        column.name.end_with?("_id") && column.name != klass.primary_key
+      end
+
+      # "Obvious" is judged purely from the column's own name against the
+      # target's actual class (including its Active Record ancestry, so a
+      # single-table-inherited subclass still matches its base class's
+      # conventional foreign key) -- never a declared association, never any
+      # other column's value, and never a second hop through another model.
+      def targets?(column, target_klass)
+        candidate = column.name.delete_suffix("_id").classify.safe_constantize
+        candidate.is_a?(Class) && (target_klass <= candidate || candidate <= target_klass)
+      end
+
+      def active_record?(record)
+        defined?(ActiveRecord::Base) && record.is_a?(ActiveRecord::Base)
+      end
+
+      def model_name(record)
+        record.class.respond_to?(:model_name) ? record.class.model_name.name.to_s : record.class.name.to_s
+      end
+
+      def primary_key_value(record)
+        record.public_send(record.class.primary_key)
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/karst/access/search.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require_relative "../value"
+require_relative "sweep"
+require_relative "principal_selection"
+require_relative "candidate_population"
+
+module Karst
+  module Access
+    # Orchestrates the two-stage search for a user who can actually use a
+    # route: the ordinary bounded sample first, then -- only if that found
+    # nothing usable -- one bounded retry against each *approved* candidate
+    # population, stopping at the first verified success.
+    #
+    # This is deliberately an orchestrator built on top of the existing
+    # primitives rather than new behavior inside them. Access::Sweep still
+    # owns every actual request (and therefore every rollback, write
+    # observation, exception, and halted-callback observation), and
+    # CandidatePopulation still owns resolving one configured callable into
+    # bounded records. Search only decides what to run next and records what
+    # it chose not to run.
+    #
+    # Approval boundary: the populations considered here are exactly the
+    # ones on the Karst::Access::PrincipalSource objects handed to this
+    # class -- which means either explicit configuration
+    # (config.principal_populations, or a config.principal_sources[...]
+    # :populations entry) or a candidate a developer explicitly approved
+    # locally, folded into the same configuration by
+    # Karst::Access::ApprovedPopulations. A name merely *discovered* by
+    # Karst::Access::PopulationDiscovery, and never approved, is never
+    # executed. Search itself deliberately cannot tell the two apart and
+    # never reads approval state: whatever produced this source's
+    # populations already had to answer for them.
+    # rubocop:disable Metrics/ClassLength
+    class Search
+      # Why a population contributed nothing, kept explicit rather than
+      # inferred from an empty result so the panel can say what actually
+      # happened instead of implying every population was tested:
+      #
+      #   :usable           ran, and produced a usable outcome
+      #   :no_match         ran, and produced no usable outcome
+      #   :empty            resolved, but currently matches no records
+      #   :already_tried    resolved, but every candidate was already tested
+      #   :unresolved       the callable did not yield usable records
+      #   :skipped          not tried -- a usable user was already found
+      #   :budget_exhausted not tried -- the retry request budget was reached
+      #
+      # Hard ceiling on the LIMIT any single population resolution may use,
+      # independent of how many users have already been tested. See
+      # #resolve_limit.
+      MAX_RESOLUTION_LIMIT = 50
+
+      PopulationAttempt = Value.define(:name, :source_name, :state, :result, :error) do
+        def ran?
+          !result.nil?
+        end
+      end
+
+      # `initial` is the ordinary Access::Sweep::Result; `attempts` is one
+      # PopulationAttempt per approved population, in configuration order,
+      # including the ones deliberately not run.
+      # rubocop:disable Metrics/BlockLength
+      Result = Value.define(:initial, :attempts) do
+        def path
+          initial.path
+        end
+
+        def http_method
+          initial.http_method
+        end
+
+        # Every outcome observed across both stages, initial sample first.
+        def all_outcomes
+          ([initial] + attempts.filter_map(&:result)).flat_map(&:outcomes)
+        end
+
+        def attempted
+          attempts.select(&:ran?)
+        end
+
+        def population_request_count
+          attempted.sum { |attempt| attempt.result.outcomes.size }
+        end
+
+        # The winning evidence and its origin are exposed by Search itself so
+        # adapters never need to invent another definition of usable access.
+        def verified_outcome
+          all_outcomes.find { |outcome| Karst.config.usable_access_outcome.call(outcome) }
+        end
+
+        def verified_source
+          return nil unless verified_outcome
+          return { type: :sample, name: nil } if initial.outcomes.include?(verified_outcome)
+
+          attempt = attempts.find { |item| item.result&.outcomes&.include?(verified_outcome) }
+          { type: :population, name: attempt.name }
+        end
+
+        def request_count
+          initial.outcomes.size + population_request_count
+        end
+
+        def elapsed_ms
+          ([initial] + attempted.map(&:result)).sum(&:elapsed_ms).round(1)
+        end
+      end
+      # rubocop:enable Metrics/BlockLength
+
+      def initialize(path:, http_method: "GET", sources: nil, application: nil)
+        @path = path
+        @http_method = http_method
+        @sources = sources || {}
+        @application = application
+        @requests_used = 0
+        @tried_keys = {}
+      end
+
+      def call
+        initial = initial_sweep
+        return Result.new(initial: initial, attempts: [].freeze) if usable?(initial.outcomes) || approved.empty?
+
+        Result.new(initial: initial, attempts: attempt_populations.freeze)
+      end
+
+      private
+
+      # PrincipalSampler is population-free by construction, so stage one
+      # cannot silently consume a population no matter what is configured;
+      # this class is the only thing that ever resolves or probes one.
+      def initial_sweep
+        sampled = PrincipalSelection.new(sources: @sources).call
+        record_tried(sampled.principals)
+        Sweep.new(path: @path, http_method: @http_method, principals: sampled.principals,
+                  application: @application, candidate_pool_size: sampled.candidate_pool_size,
+                  sampling_reasons: sampling_reasons(sampled)).call
+      end
+
+      def sampling_reasons(sampled)
+        sampled.candidates.to_h { |candidate| [candidate.principal, candidate.reasons] }
+      end
+
+      # Configuration order, across sources and then within each source --
+      # Ruby Hashes preserve insertion order, so this is exactly the order
+      # the application declared (explicitly configured populations first,
+      # then locally approved ones in their own stable model/scope order),
+      # never a heuristic ranking.
+      def approved
+        @approved ||= @sources.flat_map do |source_name, source|
+          source.populations.map { |name, callable| [source_name, name, callable, source] }
+        end
+      end
+
+      def attempt_populations
+        found = false
+        approved.map do |source_name, name, callable, source|
+          next skip(source_name, name, :skipped) if found
+
+          attempt = attempt_population(source_name, name, callable, source)
+          found = attempt.state == :usable
+          attempt
+        end
+      end
+
+      def attempt_population(source_name, name, callable, source)
+        return skip(source_name, name, :budget_exhausted) unless budget_remaining.positive?
+
+        resolved = candidate_records(source_name, name, callable, source)
+        return resolved if resolved.is_a?(PopulationAttempt)
+
+        sweep_population(source_name, name, resolved[:records], resolved[:population])
+      rescue StandardError => e
+        skip(source_name, name, :unresolved, error: "#{e.class}: #{e.message}")
+      end
+
+      # Returns either the records to probe or a terminal PopulationAttempt
+      # explaining why there are none. Resolution costs exactly one bounded
+      # LIMIT query -- never a COUNT, never full materialization.
+      def candidate_records(source_name, name, callable, source)
+        klass = source.record_klass
+        return skip(source_name, name, :unresolved, error: "source is not an Active Record model") unless klass
+
+        population = CandidatePopulation.resolve(name: name, callable: callable, source_klass: klass,
+                                                 limit: resolve_limit)
+        return skip(source_name, name, :unresolved, error: "did not resolve to a usable relation") unless population
+        return skip(source_name, name, :empty) if population.records.empty?
+
+        fresh_records(source_name, name, population)
+      end
+
+      def fresh_records(source_name, name, population)
+        fresh = population.records.reject { |record| @tried_keys.key?(identity_key(record)) }
+        return skip(source_name, name, :already_tried) if fresh.empty?
+
+        { records: fresh.first(per_population_limit), population: population }
+      end
+
+      def sweep_population(source_name, name, records, population)
+        record_tried(records)
+        @requests_used += records.size
+        result = Sweep.new(path: @path, http_method: @http_method, principals: records, limit: records.size,
+                           application: @application,
+                           sampling_reasons: population_reasons(records, population)).call
+        state = usable?(result.outcomes) ? :usable : :no_match
+        PopulationAttempt.new(name: name, source_name: source_name, state: state, result: result, error: nil)
+      end
+
+      def population_reasons(records, population)
+        records.to_h { |record| [record, [population.provenance]] }
+      end
+
+      def skip(source_name, name, state, error: nil)
+        PopulationAttempt.new(name: name, source_name: source_name, state: state, result: nil, error: error)
+      end
+
+      # Resolving a few more rows than will actually be probed guarantees
+      # deduplication cannot produce a false ":already_tried": if a
+      # population holds at least (cap + already-tried) rows, at most
+      # already-tried of them can be duplicates, so at least `cap` fresh
+      # ones survive.
+      #
+      # MAX_RESOLUTION_LIMIT caps that explicitly rather than leaving it to
+      # an indirect argument about how large the already-tried set can get.
+      # Without the cap the limit is (cap + already-tried), and already-tried
+      # grows with both the initial sample and every prior population, so a
+      # late population would be resolved with a needlessly large LIMIT. The
+      # cap costs only the guarantee above, and only for a population whose
+      # rows are almost entirely duplicates -- which reports
+      # ":already_tried", still an honest answer.
+      def resolve_limit
+        [per_population_limit + @tried_keys.size, MAX_RESOLUTION_LIMIT].min
+      end
+
+      def per_population_limit
+        [Karst.config.population_retry_limit, budget_remaining].min
+      end
+
+      # The whole retry stage may never issue more requests than an ordinary
+      # sweep already may, so enabling populations at most doubles the cost
+      # of an analysis regardless of how many are configured.
+      def budget_remaining
+        Karst.config.access_sweep_limit - @requests_used
+      end
+
+      def usable?(outcomes)
+        policy = Karst.config.usable_access_outcome
+        outcomes.any? { |outcome| policy.call(outcome) }
+      end
+
+      def record_tried(records)
+        records.each { |record| @tried_keys[identity_key(record)] = true }
+      end
+
+      # Identity by model plus primary key, so the same row arriving as two
+      # separate Active Record instances (once from the sample, once from a
+      # population) is recognised as already tested. Falls back to object
+      # identity for anything without an id, which is never worse than the
+      # previous behaviour of always re-probing.
+      def identity_key(record)
+        id = record.respond_to?(:id) ? record.id : nil
+        id.nil? ? [nil, record.object_id] : [record.class.name, id]
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end