karst 0.1.0

data/docs/advanced-configuration.md

@@ -0,0 +1,188 @@
+# Advanced configuration
+
+Almost nothing here is part of installing Karst. A conventional single-model Devise application configures none of it — see [README.md](../README.md). This document is for the exceptions: custom authentication, identity spread across several models, populations committed as code, and a few bounds an ordinary developer should never need to change. See [ARCHITECTURE.md](../ARCHITECTURE.md) for how these pieces are implemented.
+
+If you are looking for an option that used to be here, check [Removed configuration](#removed-configuration) at the end.
+
+## Custom or non-Devise authentication
+
+Karst does not assume identity is a `User`, an Active Record object, or a Warden session. Configure a lazy candidate source and the hooks a probe session uses to sign in and out:
+
+```ruby
+Karst.configure do |config|
+  config.principals = -> { Account.active }
+  config.assume_identity = lambda do |session, account|
+    session.post "/karst_test_login", params: { account_id: account.id }
+  end
+  config.clear_identity = ->(session) { session.delete "/karst_test_logout" }
+
+  # Optional, only evaluated when a display label is needed:
+  config.principal_label = ->(account) { "QA account #{account.id}" }
+end
+```
+
+`config.principals` is called only by `Karst::Identity.principals` — Karst never enumerates, samples, or materializes its result itself. `assume_identity` and `clear_identity` must be configured together. This lets an app use a test-only login endpoint or any other session-local mechanism without ever handing Karst a password, email, token, or other credential.
+
+`bin/rails generate karst:install` is an optional escape hatch for custom authentication. You usually do not need this generator: conventional single-model Devise apps require no initializer, application controller, or Karst routes. The compatibility-preserving command scaffolds a compact initializer, a `KarstIdentityController` with explicit `TODO`s, and development-only routes. Replace the `TODO`s with your app's real sign-in/sign-out behavior. None of this is required if you already configure Karst by hand.
+
+Browser **Test as** needs a second, separate pair of hooks, because they mutate the real Rack request/session rather than an isolated probe session:
+
+```ruby
+Karst.configure do |config|
+  config.assume_browser_identity = lambda do |request, account|
+    request.session[:account_id] = account.id
+  end
+  config.clear_browser_identity = lambda do |request|
+    request.session.delete(:account_id)
+  end
+end
+```
+
+When both are configured, every usable user in the results gets a **Test as** button. Karst resolves the submitted user only through a configured principal source, then invokes the hook, then redirects back to the exact page you were testing.
+
+Because `/karst` is served at the Rack boundary, before Action Controller, Rails' authenticity-token helpers aren't available there. Karst instead stores a random nonce in the existing Rack session and requires a constant-time match on every identity-changing POST. This path is local-development-only, requires a writable host session, never accepts an external return URL, and stays inactive unless both browser hooks are configured.
+
+## Authentication identifiers in local human output
+
+Without `config.principal_label`, Karst normally labels a principal `Model #id`.
+For a Devise-mapped model, Karst may make the **local HTML panel and human CLI**
+more recognizable by reading the model's single, explicitly declared
+`authentication_keys` field (for example, `email`) and showing
+`user@example.com · User #27`. Email is a `mailto:` link in HTML.
+
+This is deliberately evidence-based rather than a column-name heuristic. Karst
+does not scan for `name`, `phone`, `address`, tokens, passwords, or likely login
+columns. No identifier is read when Devise is unavailable, the principal's
+model is not mapped by Devise, the declared key is missing, its value is nil or
+empty, or Devise declares multiple authentication keys. Multiple keys fail
+closed because Karst cannot determine which key is appropriate to disclose.
+
+Framework-inferred identifiers are **never serialized in `--json` output or MCP
+output**; those interfaces retain `Model #id`. A callable
+`config.principal_label` still overrides inference completely, is not being
+deprecated here, and remains explicit application consent for that configured
+label to appear in all existing outputs.
+
+## Multiple user models: `config.principal_sources`
+
+Some apps represent identity as more than one model (`Author`, `Reader`) rather than one `User` with a role column:
+
+```ruby
+Karst.configure do |config|
+  config.principal_sources = {
+    authors: { records: -> { Author.all }, populations: { admins: -> { Author.admins } } },
+    readers: -> { Reader.all }
+  }
+end
+```
+
+Each source is a name plus a lazily-evaluated `records:` callable, and optional `populations:` of its own. Those are the only two keys a source spec accepts; anything else raises `ArgumentError` rather than being quietly ignored. Sources are never merged together — Karst keeps each independently queryable and never confuses `Author #12` with `Reader #12`. `config.principals` (plus `config.principal_populations`) remains fully supported; it's normalized internally into one implicit `:default` source, so this is additive, not a breaking change to the simple form in the main README.
+
+Candidates are split across sources within one overall `access_sweep_limit`: every non-empty source gets at least one candidate, and the rest fill round-robin so one source running dry never starves another.
+
+## Several Devise models, selected locally
+
+`config.principal_sources` above is the way to commit multiple sources as reviewable Ruby. If your app simply has more than one Devise model (`User`, `Admin`) and nothing configured, Karst still refuses to guess which one(s) to test — but you don't have to write an initializer to resolve that. The `/karst` panel shows every Devise-detected model as a checkbox right where the old "configure `config.principals`" message used to sit:
+
+```
+Karst found 2 user types: Admin, User.
+
+Which should Karst test?
+
+[ ] Admin
+[ ] User
+
+[Save]
+```
+
+Checking one model behaves exactly like a single-model Devise app always has. Checking more than one produces exactly what `config.principal_sources` would: one independently queryable source per model, each keyed by its own Devise/Warden scope (`User` → `:user`, `Admin` → `:admin`) — never collapsed into a combined source, and probe/browser identity always uses the correct scope for whichever source actually produced a given principal.
+
+The selection is saved to `tmp/karst/principal_source_selection.json`, relative to `Rails.root` — the same machine-local, git-ignored, development/test-only mechanism candidate-population approval already uses (see [Curating candidate populations](#curating-candidate-populations) below): a bare model name, nothing else, revalidated against Devise's own current `Devise.mappings` on every read. A selected model Devise no longer maps (removed, renamed) is silently dropped rather than trusted, and if that empties the selection entirely, Karst is ambiguous again and asks once more. An explicitly configured `config.principals`/`config.principal_sources` always wins outright over a saved selection, exactly like it wins over Devise inference. Once saved, `/karst`, `bin/rails karst:verify`, and the MCP `verify_access` tool all pick it up automatically, with no separate wiring — and both return the same actionable, structured error before anything is selected.
+
+## Representative sampling
+
+Nothing here is configurable — it is documented so you can read Karst's output, not so you can tune it.
+
+When `config.principals` (or a source's `records:`) returns an Active Record relation, Karst doesn't just take whichever rows sort first. It fetches one bounded, recent pool (`principal_candidate_pool_size`, default 1,000 rows, exactly one query) and then, in memory over that pool, tries to cover a handful of different observed states: boolean columns, enum columns, presence/absence of a nullable foreign key, and low-cardinality scalar columns (2–10 distinct values). Anything that looks like PII by name (email, phone, address, token, password, and similar) is excluded outright, as is anything shaped like a tenant/account/organization foreign key.
+
+That produces the `Sampled for: role=local_admin` line next to a usable user. It is sampling evidence, never an authorization claim — Karst never states or implies that the role is what let the request through.
+
+When the right user is too rare for this to reach — a role held by three people out of 400,000 — that is what candidate populations are for, and they are a separate, later search stage with its own reporting.
+
+## Curating candidate populations
+
+Writing `config.principal_populations` by hand works well once you know which scopes matter. On a large app, finding them by reading source is tedious — so Karst separates **discovery** (automatic, executes nothing) from **approval** (always an explicit developer action).
+
+**Discovery.** `Karst::Access::PopulationDiscovery` parses application model source with Ruby's standard-library `Ripper` AST parser and lists statically named, zero-argument Rails `scope` declarations. It never calls a scope, never queries anything, and never mutates application state. Only scopes declared directly on a model are found; scopes contributed by a `concern` may not appear. `bin/rails karst:populations` prints every discovered model and scope name, marking the approved ones; discovery is not approval — Karst finding `User.system_admins` says only that such a scope exists, never that it grants access.
+
+**Approval.** When an analysis finds no usable user and unapproved candidates exist, `/karst` links to `/karst/populations`: candidates grouped by model, collapsed and searchable. Checking a scope and pressing **Preview** runs one bounded (`LIMIT 3`) query, inside a rolled-back transaction, to show a few matching records — optional, never required to approve. Pressing **Approve selected groups** persists the selection to `tmp/karst/approved_populations.json`, relative to `Rails.root`:
+
+```json
+{ "version": 1, "approved": [{ "model": "User", "scope": "system_admins" }] }
+```
+
+Deliberately machine-local, git-ignored development state, not project configuration — delete the file to reset every approval. It holds **only model and scope names**, never user data, never a `-> { ... }` lambda, and Karst never evaluates its contents; an entry is only ever compared, as a string, against what current discovery still confirms. This is what keeps the file from becoming an arbitrary-method allowlist: a hand-edited entry naming an ordinary class method (`destroy_all`) is never confirmed, and an approval whose scope was renamed, given parameters, or deleted stops being executed the moment the source changes — shown as stale on the review page rather than silently dropped.
+
+An approval only ever becomes executable for a model that is already a configured or Devise-inferred principal source (the class always comes from that source, never from the file), and only in development/test — production never reads the file. `config.principal_populations`/`config.principal_sources[...] :populations` keeps working unchanged and wins outright over an approval of the same name; Karst compares by name only, since it never inspects a configured callable's body. Approved populations reach `Access::Search` the same way configured ones do, so `/karst`, `bin/rails karst:verify`, and the MCP `verify_access` tool all pick them up automatically with no adapter-specific wiring.
+
+The review page can still generate a ready-to-paste `config.principal_populations = { ... }` (or `config.principal_sources = { ... }`) snippet from your approvals, under **Advanced: export approvals as Ruby** — useful for committing populations as reviewable code, or for CI, where machine-local approval state is deliberately not consulted.
+
+## Resource evidence
+
+When a usable user is found for a route with an `:id` segment (`/admin/imports/123`), Karst separately checks whether that exact resource and that exact user share a direct foreign-key relationship — for example, that `Document#22`'s `user_id` column equals `User#27`'s id. Only columns ending in `_id` are ever inspected, and only a direct column-value comparison is made — never a join or a `has_many` traversal, and no other attribute (name, email, token) is ever read. This is shown as **Related state** on a usable result when available, and simply omitted otherwise.
+
+## Full configuration reference
+
+This is the entire public configuration surface. Every entry is either an escape hatch for an application Karst cannot infer, or a bound with a working default.
+
+### Normal
+
+```ruby
+config.enabled = true    # default: development/test only
+```
+
+The single switch that turns Karst's whole development surface off — `/karst`, the page badge, `bin/rails karst:verify`, and the MCP `verify_access` tool all refuse to run when it is false. Karst is off in production regardless.
+
+### Escape hatches
+
+| Option | For |
+| --- | --- |
+| `principals` | Custom or non-Devise authentication ([above](#custom-or-non-devise-authentication)) |
+| `assume_identity` / `clear_identity` | Signing a probe session in and out; must be configured together |
+| `assume_browser_identity` / `clear_browser_identity` | Browser **Test as** under custom authentication |
+| `principal_label` | A display label for a non-Active-Record principal |
+| `principal_sources` | Identity spread across several models ([above](#multiple-user-models-configprincipal_sources)) |
+| `principal_populations` | Populations committed as reviewable code, or needed in CI ([above](#curating-candidate-populations)) |
+
+### Bounds
+
+Defaults are chosen to be safe on a large application; changing them is rarely the right fix.
+
+```ruby
+config.access_sweep_limit = 25                # users tried per search (1–100)
+config.principal_candidate_pool_size = 1_000  # recent-row pool for sampling (1–10,000)
+config.population_retry_limit = 3             # records tried per population (1–10)
+config.usable_access_outcome = ->(outcome) { outcome.status == 200 && ... }
+```
+
+Each numeric bound raises `ArgumentError` outside its range rather than clamping. `usable_access_outcome` lets you redefine what counts as "usable" without changing what evidence is captured — for example, treating a `204` as usable for an API endpoint. The default is: HTTP 200, no observed exception, no halted callback.
+
+## Removed configuration
+
+Karst is pre-1.0 and prefers a clean surface to accumulated accidental complexity. These options existed in earlier product directions and are gone. Setting one raises `Karst::RemovedConfiguration` (a `NoMethodError`) naming the removal — Karst never silently ignores a removed option or reinterprets it as something else.
+
+| Removed | Why, and what to do instead |
+| --- | --- |
+| `config.principal_dimensions` | Sampling states are derived from your schema automatically ([above](#representative-sampling)); there is nothing to declare. A user too rare for the ordinary sample is reached through a candidate population, which reports itself as evidence. |
+| `config.artifact_source` / `config.access_scenario` | Artifact scenarios swept application records rather than routes, and had no place in the current product. Karst analyzes routes. |
+| `config.buffer_size` | Runtime SQL capture is gone: Karst kept a process-wide `sql.active_record` buffer that no Karst surface reported any more. `Karst.buffer`, `Karst.window`, `Karst::Sql::*`, and `Karst.subscribe!`/`unsubscribe!`/`subscribed?` are removed with it. Karst now installs no notification subscriber at boot, so it costs a host application nothing per query. Database writes during a probe are still observed and reported — that has always used its own scoped, per-probe subscription. |
+
+A `dimensions:` key inside a `config.principal_sources` spec raises `ArgumentError` for the same reason.
+
+## Safety detail
+
+- `/karst`, the badge, and browser Test As only run for loopback requests (and, under WSL, the single detected host-side gateway a Windows browser appears from) while `Rails.env.development?` is true. Forwarding headers and other private-network addresses are never trusted.
+- Every probe runs inside `ActiveRecord::Base.transaction(requires_new: true)` and is always rolled back. This only isolates writes made through the same Active Record connection in that request — not jobs, mail, external HTTP calls, files, Redis, or other database connections.
+- Population callables are evaluated inside that same rollback-only transaction; a population whose callable itself performs a write is rejected even though rollback was attempted, because Karst observed `INSERT`/`UPDATE`/`DELETE` SQL from it.
+- Every search is bounded: at most `access_sweep_limit` requests for the ordinary sample, and the automatic population retry stage can add at most that many again — so enabling populations can roughly double a search's cost, never more.
+- Karst never looks up a user outside a configured principal source. Submitting an arbitrary model name/id to **Test as** resolves nothing unless that model is one of your configured sources.

data/lib/generators/karst/install/install_generator.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Karst
+  module Generators
+    # `bin/rails generate karst:install`
+    #
+    # Scaffolds a compact initializer plus the development-only probe
+    # identity controller/routes a *custom* (non-Devise) identity
+    # configuration can drive. See the generated files themselves for what
+    # each seam is responsible for.
+    #
+    # This generator does not need to detect Devise/Warden itself: that
+    # detection happens at runtime, from Devise's own routing metadata (see
+    # Karst::Identity::DeviseSupport), not at generation time. A conventional
+    # single-model Devise application needs nothing from this generator.
+    # The initializer, identity controller, and routes exist only for
+    # applications that fall back to a custom `config.assume_identity` /
+    # `config.clear_identity` pair.
+    #
+    # This generator is convenience/scaffolding only. Karst remains fully
+    # configurable by hand (see README.md); nothing at runtime requires this
+    # generator to have been run, and an application that already configures
+    # Karst manually has no need to run it.
+    #
+    # Idempotent: running it again only touches files whose content actually
+    # changed, via Thor's own file-collision handling, and the routes
+    # insertion is a no-op once the exact same route block is already
+    # present.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Scaffolds the custom-authentication escape hatch (not needed for conventional Devise apps)."
+
+      DEVELOPMENT_ROUTES = <<~ROUTES
+        if Rails.env.development?
+          post   "/karst_test_login",  to: "karst_identity#create"
+          delete "/karst_test_logout", to: "karst_identity#destroy"
+        end
+      ROUTES
+      private_constant :DEVELOPMENT_ROUTES
+
+      NEXT_STEPS = <<~STEPS
+
+        You usually do not need this generator. Use it only when Karst cannot
+        infer your application's custom authentication.
+
+        1. Configure your principal source:
+           config/initializers/karst.rb
+
+        2. Implement probe identity setup/clear:
+           app/controllers/karst_identity_controller.rb
+
+        3. Implement browser Test-as identity hooks:
+           config/initializers/karst.rb
+
+        Then start Rails and visit /karst. See docs/advanced-configuration.md.
+
+      STEPS
+      private_constant :NEXT_STEPS
+
+      def copy_initializer
+        copy_file "karst_initializer.rb", "config/initializers/karst.rb"
+      end
+
+      def copy_identity_controller
+        copy_file "karst_identity_controller.rb", "app/controllers/karst_identity_controller.rb"
+      end
+
+      def add_development_routes
+        # `route` (a Rails::Generators::Actions helper) injects this exact
+        # string once via Thor's own force: false collision handling: a
+        # second run whose routes.rb already contains this text is a no-op,
+        # so this stays safe to run more than once without duplicating
+        # routes or requiring bespoke parsing of config/routes.rb.
+        route(DEVELOPMENT_ROUTES.chomp)
+      end
+
+      def post_install_message
+        say ""
+        say "Karst custom-authentication scaffold created.", :green
+        say NEXT_STEPS
+        say "Complete the TODOs with this application's real identity semantics.", :yellow
+      end
+    end
+  end
+end

data/lib/generators/karst/install/templates/karst_identity_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Development-only endpoints used by the custom probe hooks in karst.rb.
+class KarstIdentityController < ApplicationController
+  skip_before_action :verify_authenticity_token, raise: false
+
+  def create
+    principal = Karst::Identity.resolve(model_name: params[:principal_type], id: params[:principal_id])
+    return head(:forbidden) unless principal
+
+    # TODO: establish this app's authentication for principal, then return a response.
+    raise NotImplementedError, "Implement this application's custom Karst sign-in"
+  end
+
+  def destroy
+    # TODO: clear the authentication established by create, then return a response.
+    raise NotImplementedError, "Implement this application's custom Karst sign-out"
+  end
+end

data/lib/generators/karst/install/templates/karst_initializer.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Karst usually requires no initializer for Devise. This escape hatch exists
+# because this application uses custom authentication. Complete each TODO;
+# see docs/advanced-configuration.md for the full contract.
+Karst.configure do |config|
+  config.principals = -> { Account.active } # TODO: use this app's principal scope
+
+  config.assume_identity = lambda do |session, principal|
+    descriptor = Karst::Identity.describe(principal)
+    session.post "/karst_test_login", params: { principal_type: descriptor.model_name, principal_id: descriptor.id }
+  end
+  config.clear_identity = ->(session) { session.delete "/karst_test_logout" }
+
+  # TODO: replace :account_id with this app's browser-session identity.
+  config.assume_browser_identity = ->(request, principal) { request.session[:account_id] = principal.id }
+  config.clear_browser_identity = ->(request) { request.session.delete(:account_id) }
+end

data/lib/karst/access/approved_populations.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "population_approvals"
+require_relative "population_discovery"
+
+module Karst
+  module Access
+    # Turns locally approved candidate populations (see
+    # Karst::Access::PopulationApprovals) back into ordinary
+    # Karst::Access::PrincipalSource populations, so that everything
+    # downstream -- Access::Search, the panel, `bin/rails karst:verify`, the
+    # MCP `verify_access` tool -- keeps reading exactly one source of truth
+    # (Configuration#principal_sources) and needs to know nothing about
+    # approval at all.
+    #
+    # Three independent conditions must hold before an approved entry becomes
+    # executable, and any one of them failing silently drops it:
+    #
+    #   1. Karst is running in a local development/test environment. An
+    #      approval file that reaches production (committed by accident,
+    #      copied into an image) approves nothing there.
+    #   2. The entry's model name matches the Active Record class of an
+    #      already-configured (or inferred) principal source. The class is
+    #      taken from that source -- never looked up, constantized, or loaded
+    #      from the stored name -- so approval can only ever widen sampling
+    #      within a model the application already pointed Karst at.
+    #   3. Current source-based discovery still confirms that exact
+    #      zero-argument `scope` declaration on that class. A scope that was
+    #      removed, renamed, or given parameters stops being executed the
+    #      moment the source changes, with no file edit required, and a
+    #      hand-written entry naming an arbitrary class method is never
+    #      confirmed in the first place.
+    #
+    # Explicit configuration always wins: a population name a source already
+    # configures is never replaced or duplicated by an approved entry of the
+    # same name, and configured populations keep their configured order ahead
+    # of approved ones (see Access::Search, which tries them in exactly this
+    # order).
+    module ApprovedPopulations
+      class << self
+        # Returns a Hash of the same shape it was given, with each source's
+        # populations extended by whatever its model has approved and
+        # confirmed. Returns the argument untouched when nothing applies, so
+        # the overwhelmingly common "no approvals" case costs one file stat.
+        def merge(sources)
+          return sources unless sources && local_environment?
+
+          record = PopulationApprovals.load
+          return sources if record.entries.empty?
+
+          discovery = PopulationDiscovery.new
+          sources.each_with_object({}) do |(name, source), merged|
+            merged[name] = extend_source(source, record.entries, discovery)
+          end
+        rescue StandardError
+          # Approval is an optional convenience layered over configuration
+          # Karst already had. If resolving it fails for any reason, the
+          # honest degradation is "explicitly configured populations only" --
+          # never a broken panel, CLI, or MCP tool.
+          sources
+        end
+
+        # Every approved entry that is not currently confirmed for any of the
+        # given sources, as [Entry, reason] pairs -- the honest "this
+        # approval exists but does nothing" list the panel shows. Never
+        # executes anything.
+        def stale(sources, record: PopulationApprovals.load, discovery: PopulationDiscovery.new)
+          klasses = source_klasses(sources)
+          record.entries.filter_map do |entry|
+            klass = klasses[entry.model_name]
+            next [entry, :no_principal_source] unless klass
+            next [entry, :not_discovered] unless discovery.confirms?(klass: klass, method_name: entry.method_name)
+
+            nil
+          end
+        end
+
+        # Karst's local approval workflow is a development affordance and
+        # nothing else. Test is included so an application's own test suite
+        # (and Karst's) can exercise it; every other environment, production
+        # included, ignores the file entirely.
+        def local_environment?
+          return false unless defined?(Rails) && Rails.respond_to?(:env)
+
+          env = Rails.env
+          env.respond_to?(:development?) && (env.development? || env.test?)
+        end
+
+        private
+
+        def extend_source(source, entries, discovery)
+          klass = source.record_klass
+          return source unless klass
+
+          approved = confirmed_populations(klass, entries, discovery, source.populations)
+          approved.empty? ? source : source.with_populations(approved)
+        end
+
+        # The callable built here closes over the class object Karst already
+        # held and a scope name discovery just confirmed -- no eval, no
+        # const_get, no stored Ruby. It is an ordinary configured-population
+        # callable from this point on, resolved (bounded, rollback-wrapped,
+        # write-rejecting) by Access::CandidatePopulation like any other.
+        def confirmed_populations(klass, entries, discovery, configured)
+          entries.each_with_object({}) do |entry, approved|
+            next unless entry.model_name == klass.name
+
+            name = entry.method_name.to_sym
+            next if configured.key?(name) || approved.key?(name)
+            next unless discovery.confirms?(klass: klass, method_name: name)
+
+            approved[name] = -> { klass.public_send(name) }
+          end
+        end
+
+        # Deliberately keyed by model name: two principal sources over the
+        # same model share that model's approvals, and an approval for a
+        # model no source exposes belongs to none of them.
+        def source_klasses(sources)
+          (sources || {}).each_with_object({}) do |(_name, source), klasses|
+            klass = source.record_klass
+            klasses[klass.name] = klass if klass&.name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/karst/access/candidate_population.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../value"
+require_relative "database_isolation"
+
+module Karst
+  module Access
+    # An application-authored, bounded subset of a model's rows -- for
+    # example the rows a configured callable like `-> { User.system_admins }`
+    # returns. A population is a hint about where meaningful sampling
+    # candidates might live; it is never a claim about behavior or
+    # authorization -- only Access::Sweep's runtime execution produces that
+    # evidence. See README "Candidate populations" for the full boundary
+    # this class exists to preserve.
+    #
+    # Deliberately generic over what a "candidate" represents. Today's only
+    # caller (PrincipalSampler) always treats these records as principals,
+    # but nothing here assumes that -- a future artifact-population caller
+    # (Subscription.renewable, Import.with_sheets) could resolve populations
+    # exactly the same way over a non-principal model, without this class
+    # changing at all.
+    #
+    # This deliberately does not claim that a configured callable is a "real"
+    # Rails named scope. Active Record exposes no reliable, public way to
+    # distinguish a method defined via the `scope` macro from an ordinary
+    # handwritten class method, so Karst only validates the one thing it can
+    # actually observe: calling the configured callable returns an
+    # ActiveRecord::Relation scoped to the same model being sampled. Whether
+    # that relation came from `scope :system_admins, -> { ... }` or a plain
+    # `def self.system_admins; ...; end` makes no difference here.
+    # rubocop:disable Metrics/BlockLength
+    CandidatePopulation = Value.define(:source, :name, :records, :provenance) do
+      class << self
+        # Resolves one configured name => callable pair into a bounded,
+        # already-queried population, or nil when calling the callable does
+        # not yield an ActiveRecord::Relation scoped to source_klass (wrong
+        # type, wrong model, or the callable itself raising -- including
+        # requiring an argument Karst never supplies). Invalid populations
+        # are skipped, never raised: a misconfigured population should
+        # degrade the candidate pool, not break the sweep. Issues at most
+        # one SELECT query, always LIMIT-bounded -- never a COUNT, never full
+        # materialization, regardless of how many rows the underlying
+        # relation matches. Evaluation and materialization happen inside a
+        # rollback-only transaction on the source model's connection. A
+        # candidate that emits mutating SQL is rejected even though Karst
+        # attempted to roll that transaction back.
+        def resolve(name:, callable:, source_klass:, limit:)
+          evaluation = evaluate(callable, source_klass, limit)
+          return nil unless usable_evaluation?(evaluation)
+
+          records = evaluation.value
+          return nil unless records
+
+          new(source: source_klass, name: name.to_sym, records: records, provenance: "population=#{name}")
+        rescue StandardError
+          nil
+        end
+
+        private
+
+        def evaluate(callable, source_klass, limit)
+          DatabaseIsolation.call(connection_class: source_klass) do
+            relation = callable.call
+            next unless relation.is_a?(ActiveRecord::Relation) && relation.klass == source_klass
+
+            bounded(relation, source_klass, limit)
+          end
+        end
+
+        def usable_evaluation?(evaluation)
+          evaluation.exception.nil? && evaluation.write_count.zero? && evaluation.database_rollback_attempted
+        end
+
+        # Only imposes primary-key ordering as a deterministic fallback when
+        # the configured relation has none of its own -- an application's
+        # own meaningful order (e.g. most-recently-flagged first) is
+        # respected rather than silently overridden.
+        def bounded(relation, klass, limit)
+          ordered = relation.order_values.empty? ? relation.order(klass.primary_key) : relation
+          ordered.limit(limit).to_a
+        end
+      end
+    end
+    # rubocop:enable Metrics/BlockLength
+  end
+end

data/lib/karst/access/database_isolation.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+require_relative "../value"
+
+module Karst
+  module Access
+    # Runs application-authored discovery code in a rollback-only transaction
+    # and observes the same mutating SQL evidence used by Access::Sweep.
+    # This is same-connection database containment, not general side-effect
+    # isolation: jobs, mail, network calls, files, Redis, and writes through
+    # other connections remain outside this boundary.
+    class DatabaseIsolation
+      MUTATION = %r{\A\s*(?:/\*.*?\*/\s*)*(INSERT|UPDATE|DELETE)\b}im
+
+      Result = Value.define(:value, :exception, :write_count, :database_rollback_attempted)
+
+      def self.call(connection_class:, &block)
+        new(connection_class, block).call
+      end
+
+      def self.mutation?(sql)
+        sql.to_s.match?(MUTATION)
+      end
+
+      def initialize(connection_class, callable)
+        @connection_class = connection_class
+        @callable = callable
+        @writes = 0
+      end
+
+      def call
+        @connection_class.transaction(requires_new: true) do
+          ActiveSupport::Notifications.subscribed(method(:observe), "sql.active_record") { capture }
+          raise ActiveRecord::Rollback
+        end
+
+        result(rollback_attempted: true)
+      rescue StandardError => e
+        @exception ||= e
+        result(rollback_attempted: false)
+      end
+
+      private
+
+      def capture
+        @value = @callable.call
+      rescue StandardError => e
+        @exception = e
+      end
+
+      def observe(_name, _start, _finish, _id, payload)
+        @writes += 1 if self.class.mutation?(payload[:sql])
+      end
+
+      def result(rollback_attempted:)
+        Result.new(value: @value, exception: @exception, write_count: @writes,
+                   database_rollback_attempted: rollback_attempted)
+      end
+    end
+  end
+end