karst 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08cd05c0ed4b829d53920c0cde0a5844fcb518f380b63616a812f7baef7a3e0d'
-  data.tar.gz: 43a7fde748e330ec79a586b2621f3110c0f77061594a456b8968d5beb0eba897
+  metadata.gz: 1c8a746d264f980f133db4f4e60538708b4323b3cdbbbfb0689ce82278bd0cce
+  data.tar.gz: 8060e9f4c93bdf891a2a19fb1195df8d3a2900ddda983bf8230117c1a1bec569
 SHA512:
-  metadata.gz: 5b34b65961902ec98e9f2d26e8d26add2f9cb20ad440d0ea5d098e95817e75abb1db4aeca809ebb662a2481ed08ef466deba5ec0c07ed192034331ddc6b3a1cc
-  data.tar.gz: 9396ea4e987e42f208e8f01d2c6e9127817ed902577dac113de07dee7187c6eb272b2126249153caa95412bd0dbe8514cec622652150244423f6d2d4beaf1db7
+  metadata.gz: ecced3eecbac561c88edb885f3eded09fa4d4cc67a3ec61e557ed4d27ef684e02c216009d2d503dbc2ec6cb69b56f379f75b37104d98cadc2eb553827bc7ba93
+  data.tar.gz: 4c71f5045b65849961c6490720a6535ab337157540a8c689a14474c66d228fdb42b95867813741df0aacf81726d4c111be78b124554a678e3cd9075d79e67752

data/ARCHITECTURE.md

@@ -5,14 +5,11 @@ This document describes how Karst is put together and the policy that governs wh
 ## Component map
 
 - `Karst::Configuration` — the whole public configuration surface, deliberately small: one on/off switch, the escape hatches for authentication Karst cannot infer, and four bounds with working defaults. It also owns `#principal_sources`, the single effective-configuration method every adapter reads. Karst installs no `ActiveSupport::Notifications` subscriber at boot; the only SQL Karst observes is what a probe itself emits, through a scoped per-probe subscription in `Access::DatabaseIsolation`.
-- `Karst::Spec::Observer` / `Spec::Reporter` — an opt-in RSpec integration that turns real spec execution (via `ActiveSupport::Notifications` and Warden's public hooks) into a deterministic JSON scenario artifact, with no source parsing and no database access.
-- `Karst::Spec::Catalog` — a read-only index over that artifact; requires none of RSpec, Rails, or a database to read an already-written catalog.
 - `Karst::Web::Middleware` / `Web::Panel` / `Web::Badge` / `Web::Locality` — Karst's development-only HTTP surface: `GET /karst` served directly at the Rack boundary (no engine, route, or controller) plus an optional page-local badge injected into eligible host HTML responses.
 - `Karst::Access::PrincipalSampler` — a bounded candidate-selection step ahead of `Access::Sweep`, with nothing configurable in it. It materializes one recent-N pool with a single `LIMIT` query, then stratifies that pool in memory over states derived from the schema itself: boolean columns, `enum` columns, nullable-foreign-key presence/absence, and low-cardinality scalars, minus anything PII- or tenancy-shaped. Its total query volume is exactly one query, independent of table size -- no discovery query, `COUNT`, unbounded scan, or live subquery. It only selects candidates and never executes a route, so `Access::Sweep` remains the sole behavioral-evidence contract. Candidate populations are deliberately not here: they are `Access::Search`'s second stage, so "the ordinary sample failed, then `system_admins` reached it" stays reportable rather than being folded into an ordinary-looking sample.
 - `Karst::Access::CandidatePopulation` — resolves one configured name => callable pair into a bounded, already-queried population plus a provenance label (`population=system_admins`), or `nil` when calling the callable does not yield an `ActiveRecord::Relation` scoped to the same model being sampled; never raises for a misconfigured population, and never issues more than one `LIMIT`-bounded query regardless of the underlying relation's row count. Preserves the configured relation's own ordering when it has one, adding a deterministic primary-key fallback only when it does not. 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 this class validates only what it can actually observe: the shape of what calling the callable returns. A population is a hint about where meaningful candidates might live -- "these records are worth trying," never "these records satisfy the behavior" -- so it carries no authorization or behavioral claim; only `Access::Sweep`'s runtime execution produces that evidence. Deliberately generic over what a candidate represents: `PrincipalSampler` is its only caller today, but nothing in this class assumes authentication, so a future artifact-population caller (`Subscription.renewable`, `Import.with_sheets`) could reuse it unchanged.
 - `Karst::Access::PrincipalSource` / `PrincipalSelection` — the multi-source layer above `PrincipalSampler`. A `PrincipalSource` is "which records may Karst consider at all": a name, a lazily-evaluated records callable, and its own optional `populations`. Those two keys are the whole spec; any other key raises rather than being ignored. `Configuration#principal_sources` normalizes either an explicit `config.principal_sources` Hash or a bare `config.principals` (plus `config.principal_populations`) into one implicit `:default` source, so every downstream consumer only ever handles "one or more sources." `PrincipalSelection` runs `PrincipalSampler` independently per source -- never materializing sources together -- and allocates combined candidates fairly within one overall `limit`, tagging `source=<name>` on candidates only once more than one source is actually configured.
 - `Karst::Access::PopulationDiscovery` / `PopulationApprovals` / `ApprovedPopulations` — the local approval workflow that removes hand-written `config.principal_populations` from the normal path. `PopulationDiscovery` parses application model source with Ripper and lists statically named, zero-parameter Rails `scope` declarations; it executes no scope, issues no query, and mutates nothing. `PopulationApprovals` is the machine-local record of which of those a developer explicitly approved (`tmp/karst/approved_populations.json`) -- plain model and scope names, never executable Ruby, never user data, never evaluated, and fails closed on any malformed, unreadable, or version-mismatched document. `ApprovedPopulations` folds an approval back into ordinary `PrincipalSource` populations inside `Configuration#principal_sources`, but only when Karst is in development/test, the entry's model name matches the Active Record class of an already-configured principal source (the class always comes from that source, never from the file), and current discovery still confirms that exact scope. Explicit configuration wins outright on name conflict and keeps its position first. Because the merge happens in the one effective-configuration method, the panel, `bin/rails karst:verify`, and the MCP `verify_access` tool inherit approvals identically and none of them reads approval state itself.
-- `Karst::Access::ResourceEvidence` — a read-only, downstream step for one already-selected `Access::Sweep` outcome. Reports simple, directly observed foreign-key relationships (column name plus id equality, nothing else) between the exact resource a route addresses and one exact principal; never a join, a `has_many` traversal, or any other attribute. Resource resolution from a route path trusts only Rails' own route recognition plus controller-to-model naming convention, while principal resolution always goes through `Karst::Identity.resolve` and therefore cannot escape `config.principals`; when either step is ambiguous it reports a limitation string rather than guessing. Deliberately a separate class from both `Sweep` and `PrincipalSampler`: it runs no route and selects no candidates, only compares two already-identified records.
 
 Each area is deliberately narrow and composable; none of them depends on the others' internals beyond the public objects listed above.
 
@@ -24,11 +21,11 @@ The guiding rule: **core Karst functionality works on Rails 6.1 even where an op
 
 ### Capability degradation
 
-| Rails / Rack       | `require "karst"` | Access search (`/karst`, CLI, MCP) | Spec Observer | Scenario Catalog | `/karst` panel | Page-local badge |
-|---------------------|:---:|:---:|:---:|:---:|:---:|:---:|
-| 6.1 / Rack 2         | yes | yes | yes | yes | yes | **unavailable** |
-| 7.0 / Rack 2         | yes | yes | yes | yes | yes | **unavailable** |
-| 7.1, 7.2, 8.x / Rack 3 | yes | yes | yes | yes | yes | yes |
+| Rails / Rack       | `require "karst"` | Access search (`/karst`, CLI, MCP) | `/karst` panel | Page-local badge |
+|---------------------|:---:|:---:|:---:|:---:|
+| 6.1 / Rack 2         | yes | yes | yes | **unavailable** |
+| 7.0 / Rack 2         | yes | yes | yes | **unavailable** |
+| 7.1, 7.2, 8.x / Rack 3 | yes | yes | yes | yes |
 
 The badge is the one capability that degrades. `Karst::Web::Badge` only ever rewrites a Rack response body that reports itself bufferable via Rack's own `to_ary` idiom (the same check `Rack::ETag` relies on for the same reason). Under Rack 2, `ActionDispatch`'s response body wrapper never exposes `to_ary`, so every response reports non-bufferable and Badge leaves it untouched — this is a real, per-response runtime check, not a hardcoded Rails-version branch, so it needs no maintenance as new Rack/Rails combinations appear. `/karst` itself does not depend on badge injection at all: it is a small, independent Rack middleware branch keyed on `PATH_INFO`, so it is unaffected. Karst never monkey-patches `ActionView`, never consumes a streaming body to work around this, and never weakens `Content-Length`, CSP, or host middleware semantics to force badge parity onto Rack 2.
 
@@ -38,12 +35,12 @@ Ruby 2.7 has no `Data.define` (added in Ruby 3.2). Every former `Data.define` si
 
 ### Request-local state: `Karst::ExecutionContext`
 
-The page badge and the spec observer both need request-local (not global, not thread-shared-and-racy) correlation storage: evidence captured inside a notification callback, read back out after the call returns. Modern Rails provides exactly this via `ActiveSupport::IsolatedExecutionState`, added in Rails 7.0. `Karst::ExecutionContext` is the seam:
+The page badge needs request-local (not global, not thread-shared-and-racy) correlation storage: evidence captured inside a notification callback, read back out after the call returns. Modern Rails provides exactly this via `ActiveSupport::IsolatedExecutionState`, added in Rails 7.0. `Karst::ExecutionContext` is the seam:
 
 - When `ActiveSupport::IsolatedExecutionState` is defined, `Karst::ExecutionContext` delegates directly to it — modern Rails keeps using its own preferred primitive, with no extra indirection cost.
 - Otherwise (Rails 6.1), it falls back to `ThreadLocalStore`, a plain per-thread `Hash` reached through `Thread#thread_variable_get`/`thread_variable_set` — deliberately not `Thread#[]`/`[]=`, which are fiber-local and would silently miss context under a Fiber scheduler.
 
-The fallback mirrors `IsolatedExecutionState`'s own default `:thread` isolation level: storage is shared by every Fiber running on one OS thread, not isolated per Fiber. Karst's own usage (one badge or spec correlation captured and read back within a single synchronous request or example) never spans multiple concurrently-scheduled Fibers, so this has no observable effect on Karst's supported behavior — it is documented so a future caller does not assume Fiber isolation the fallback cannot provide.
+The fallback mirrors `IsolatedExecutionState`'s own default `:thread` isolation level: storage is shared by every Fiber running on one OS thread, not isolated per Fiber. Karst's own usage (one badge correlation captured and read back within a single synchronous request) never spans multiple concurrently-scheduled Fibers, so this has no observable effect on Karst's supported behavior — it is documented so a future caller does not assume Fiber isolation the fallback cannot provide.
 
 Both backends share the same three-method contract (`[]`, `[]=`, `delete`), cleanup happens in the caller's own `ensure` block exactly as before, and neither backend introduces global mutable state: each thread only ever sees its own slot, so concurrent Puma requests cannot cross-contaminate each other's context.
 
@@ -56,4 +53,4 @@ Compatibility decisions live behind exactly two narrow seams — `Karst::Value`
 - `unit-test` — Ruby 3.2, the root `Gemfile` (RSpec + RuboCop against everything except `spec/integration`).
 - `rails-integration` matrix — `spec/integration` against a version-pinned `Gemfile` per row, each a real Rails application booted through Rack: Rails 6.1 on Ruby 2.7, Rails 7.0 and 7.1 on Ruby 3.2, Rails 7.2 and 8.0 on Ruby 3.3. Every row is a required, blocking job.
 
-The Rails 6.1 row is what backs the compatibility claim in this document: it boots a real `Rails::Application`, exercises `GET` against ordinary routes and `/karst`, and runs the scenario observer/catalog round trip, all against genuine Ruby 2.7 syntax and Rails 6.1 APIs — not an assumption that "this probably still works."
+The Rails 6.1 row is what backs the compatibility claim in this document: it boots a real `Rails::Application`, exercises `GET` against ordinary routes and `/karst`, all against genuine Ruby 2.7 syntax and Rails 6.1 APIs — not an assumption that "this probably still works."

data/CHANGELOG.md

@@ -1,67 +1,54 @@
 # Changelog
 
-All notable changes to Karst will be documented in this file.
+All notable changes to Karst are documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project intends to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) once releases begin.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.2.0]
 
-### Fixed
-
-- **The golden path was broken for every real Devise/Warden application.** `Karst::Access::ProbeApplication`'s deliberately minimal probe Rack stack never wrapped `Warden::Manager`, so `env["warden"]` never existed inside a probe and every principal failed with `Karst::Identity::Unavailable` instead of real observed evidence. Fixed by wrapping a `Warden::Manager` (reusing Devise's own already-configured scope defaults, session serializers, and failure app when Devise is present) directly around the router, in the same position a real host application's own compiled middleware stack uses. Because `Karst::Identity.with` establishes probe identity *before* the caller's own request runs, `Karst::Identity::WardenAdapter#assume` now queues the principal (via a thread-local, request-scoped slot -- never Warden's own global `Test::Helpers` queue, which would leak across concurrent unrelated requests) and applies it the moment that exact probe's own request reaches the newly-wrapped `Warden::Manager` -- the same queue-for-next-request idiom `Warden::Test::Helpers#login_as` and `Devise::Test::IntegrationHelpers#sign_in` already use for the identical problem in integration tests.
-- `ProbeApplication` no longer passes Devise's live `warden_config` Hash directly into `Warden::Manager.new`'s `options` argument: that constructor destructively deletes `:default_strategies` from whatever Hash it's given, silently corrupting the one shared config object every *real* host request also authenticates through -- a single Karst probe could previously break the host application's own Devise login for the rest of the process. A duplicate is used instead, and only through `Warden::Manager`'s config *block* (`Warden::Manager.new(endpoint) { |config| config.merge!(...) }`), never as constructor `options` -- passing it as `options` also mis-splats Devise's own already-per-scope `:default_strategies` Hash into `:_all`, misfiling every scope name as if it were itself a strategy and raising Warden's own `"Invalid strategy <scope>"` the moment more than one Devise model is involved.
-- `ProbeApplication::Environment#call` built a fresh, merged copy of the incoming Rack env on every call instead of mutating it in place, so any state a wrapped middleware set during the request (in particular `env["warden"]`) was invisible to the exact env object `ActionDispatch::Integration::Session` retains afterward as `#request.env` -- `WardenAdapter#clear` could never find the very proxy `#assume` had just used, raising `Karst::Identity::Unavailable` from Access::Sweep's own cleanup path even on an otherwise fully successful probe.
-- **"Stop testing as" could fail and leave the assumed identity active.** `Karst::Web::BrowserIdentity#return_path` raised when the panel's hidden `path` field was blank -- which it always is on a plain `/karst` visit with no `?path=` query string, exactly what a developer sees immediately after Test As redirects them to the page they were testing. Karst now falls back to `/karst` itself for a blank return path instead of raising.
-- **A multi-Devise application's ambiguity notice never appeared until *after* a route was already selected.** `Web::Panel#access_section` rendered nothing at all -- not even the "Karst found N user types, which should Karst test?" selection form, and not the custom-authentication pointer either -- until a URL was chosen, so a fresh multi-Devise (or non-Devise) installation's very first `/karst` visit looked entirely blank with no indication anything needed attention. The same setup notice now renders regardless of whether a route is selected yet.
+### Added
 
-### Removed
+- Documented and acceptance-tested support for Rails 8 generated authentication.
+- Added local selection of the user models Karst should test when a Devise application has multiple mappings.
+- Added inline, local approval of discovered candidate populations after an unsuccessful ordinary sample.
+- Added `config.population_retry_limit` for bounding approved-population retries.
 
-- **`config.principal_dimensions`.** Declaring which coarse states Karst should try to cover during the ordinary sample is no longer part of the product. Schema-derived stratification (boolean columns, `enum` columns, nullable-foreign-key presence/absence, low-cardinality scalars, minus anything PII- or tenancy-shaped) was already the zero-configuration path and is now the only one; a configured dimension replaced it wholesale rather than improving it, so the option could only ever make sampling narrower than the default. The case it actually existed for -- a user too rare for a recent sample to reach -- is what candidate populations are for, and those report themselves as named evidence instead of quietly reshaping an ordinary-looking sample. `Karst::Access::PrincipalDimension` is removed. `Karst::Access::PrincipalSource` no longer accepts `dimensions:`, and a `dimensions:` key inside a `config.principal_sources` spec now raises `ArgumentError` rather than being silently ignored -- as does any other unrecognized key. Scalar sampling reasons render plainly (`role=local_admin`, not `role="local_admin"`), preserving exactly what the panel displayed before.
-- **`config.artifact_source` / `config.access_scenario`.** Explicit artifact scenarios swept application records ("can any recent import be opened cross-account?") rather than answering "which user can reach this route," had no entry point in the primary workflow, and were already absent from the README. `Karst::Access::ArtifactSource`, `Access::Scenario`, and `Access::ScenarioSweep` are removed along with the panel's per-scenario buttons and the middleware's `artifact_sweep` operation.
-- **`config.buffer_size`, and the runtime SQL evidence subsystem with it.** Karst kept a process-wide, bounded `sql.active_record` buffer from an earlier product direction; no Karst surface has reported it since `/karst` was restructured around access search, so a host application was paying a notification callback on every query for evidence nobody could see. `Karst.buffer`, `Karst.window`, `Karst.subscribe!`/`unsubscribe!`/`subscribed?`, `Karst::Buffer`, `Karst::Subscription`, and `Karst::Sql::Event`/`Canonicalizer`/`Shape`/`Window` are removed, as is the railtie's `after_initialize` subscription. **Karst now installs no `ActiveSupport::Notifications` subscriber at boot at all.** Database-write evidence during a probe is unaffected: it has always come from `Access::DatabaseIsolation`'s own scoped, per-probe subscription, not from this buffer.
+### Changed
 
-Setting any removed option raises `Karst::RemovedConfiguration` (a `NoMethodError` subclass) with a message naming the removal and what replaced it. Karst never silently ignores a removed option or reinterprets it as something else. See [docs/advanced-configuration.md](docs/advanced-configuration.md#removed-configuration).
+- Candidate-population approval now happens inline in the failed `/karst` result, followed by an immediate retry.
+- `/karst/populations` is limited to inspecting and revoking stored approvals, including stale approvals.
+- MCP support is opt-in instead of a runtime dependency of the gem.
+- The product surface is simplified around route-access verification: an ordinary bounded sample followed, when needed, by a separate bounded search of approved candidate populations.
+- `config.enabled` now gates all of Karst's development surfaces.
 
-### Changed
+### Removed
 
-- **`config.enabled` now actually gates Karst.** It previously controlled only the SQL subscription removed above, which meant setting `config.enabled = false` disabled nothing a developer could observe -- `/karst`, the badge, `bin/rails karst:verify`, and the MCP `verify_access` tool all kept working, contradicting the README. It is now the single switch for Karst's whole development surface, re-read live on every request so turning Karst off never depends on initializer ordering. The default is unchanged (development/test only), and production remains off regardless.
-- Configuration is restructured around "usually, you don't": the README's configuration section is now the off switch and a pointer, and every remaining option is documented in [docs/advanced-configuration.md](docs/advanced-configuration.md) as either an escape hatch for authentication Karst cannot infer or a bound with a working default. `access_sweep_limit`, `principal_candidate_pool_size`, `population_retry_limit`, and `usable_access_outcome` remain configurable but no longer appear on the normal installation path.
+- The `Karst::Spec::*` observer, catalog, and scenario subsystem.
+- `Karst::Access::ResourceEvidence` and inferred resource-relationship presentation.
+- Candidate-population preview and Ruby-snippet export.
+- The `karst:populations` rake task.
+- Redundant population-management and discovery UI superseded by inline approval.
+- The unused runtime SQL buffer and its public `Karst.buffer` and `Karst.window` analysis surface.
+- Unused artifact scenarios and configurable principal dimensions.
 
-- Candidate populations leave `Karst::Access::PrincipalSampler` entirely and become a deliberate second search stage owned by `Karst::Access::Search`, run only when the ordinary sample finds nothing usable — so "the sample found nothing; then `system_admins` reached it" is reportable as observed evidence rather than silently folded into an ordinary-looking sample. `PrincipalSampler` and `PrincipalSelection` no longer accept or report populations, and the sampler's query budget drops to exactly one bounded recent-pool query. Configured dimensions still shape the ordinary sample, with generic schema discovery as their fallback.
-- The manual `population_sweep` operation and its "Try another population" panel section are removed, along with `Karst::Access::PopulationSuggestion` (its name-ranking heuristic only existed to order that manual choice). Retries are automatic.
-- Panel copy now says "user" rather than "principal" in the access workflow.
-- `/karst/populations` is reorganized around approval rather than snippet generation: candidate groups are approved with a checkbox and one **Approve selected groups** button, approvals and stale approvals are surfaced first, and Ruby snippet generation moves to an advanced export path for applications that prefer to commit their populations (or for CI, where machine-local approval state is deliberately not consulted). Preview remains available, bounded and rollback-safe, and is never required in order to approve. The page's POST operations now require a same-origin request, since approving writes local state that outlives the request.
+## [0.1.0]
 
 ### Added
 
-- **Local selection of an ambiguous Devise setup, so a multi-model Devise app no longer needs an initializer to resolve it.** Karst still refuses to guess when `Devise.mappings` reports more than one model and nothing is explicitly configured — that safety boundary is unchanged — but the `/karst` panel now shows every detected model as a checkbox right where the old "configure `config.principals` explicitly" message used to sit, and one **Save** persists the choice. Selecting one or more models produces the same `Karst::Access::PrincipalSource` machinery an explicit `config.principal_sources` would: one independently queryable source per selected model, keyed by that model's own Devise/Warden scope (`User` → `:user`, `Admin` → `:admin`), never collapsed into a combined source. The selection is recorded by the new `Karst::Access::PrincipalSourceSelection` in `tmp/karst/principal_source_selection.json` — the same machine-local, git-ignored, development/test-only mechanism candidate-population approval already uses — holding only bare model names, never executable Ruby, never constantized; `Karst::Access::SelectedPrincipalSources` revalidates every entry against Devise's own current metadata on every read, silently dropping a model Devise no longer maps, and reverting to the ambiguous prompt if that empties the selection entirely. An explicit `config.principals`/`config.principal_sources` always wins outright over a saved selection. Probe identity already resolved Devise/Warden scope per principal regardless of source count; browser identity eligibility and **Stop testing as** now do the same — the browser session retains the exact scope an assumed identity was established under, so clearing never has to guess which of several selected sources produced it. `/karst`, `bin/rails karst:verify`, and the MCP `verify_access` tool all pick up a saved selection automatically, and both CLI and MCP return the same actionable, structured error (pointing at `/karst` instead of at Ruby configuration) while nothing is selected yet.
-- **Local approval of discovered candidate populations, so `config.principal_populations` is no longer part of the normal workflow.** A developer who installs Karst and finds no usable user at `/karst` now sees one small contextual action (`Karst found 3 application-defined user groups that could be tried — Review candidate groups`), approves the groups Karst may try at `/karst/populations`, and from then on those groups are searched automatically — with no initializer editing, no generated Ruby to paste, and identical behavior through `/karst`, `bin/rails karst:verify`, and the MCP `verify_access` tool. Discovery is unchanged and remains conservative (`Karst::Access::PopulationDiscovery`: statically named, zero-parameter Rails `scope` declarations parsed from application model source with Ripper; no execution, no query, no state change) — and **discovery is still not approval**. Approval is recorded by `Karst::Access::PopulationApprovals` in `tmp/karst/approved_populations.json`, deliberately machine-local, git-ignored development state rather than committed project configuration; it holds only model and scope names (never user data, never executable Ruby, never a lambda) and Karst never evaluates it. `Karst::Access::ApprovedPopulations` folds approvals into `Configuration#principal_sources` — the single source of truth every adapter already reads — only when Karst is in development/test, only for a model that is already a configured or inferred principal source (the class always comes from that source, never from the file), and only while current discovery still confirms that exact scope, so a removed or renamed scope stops being executed with no file edit (and is shown as unused on the review page), and a hand-written entry naming an ordinary class method is never confirmed at all. A malformed, unreadable, or version-mismatched approval file approves nothing and says so. Explicit `config.principal_populations`/`config.principal_sources[...] :populations` keeps working unchanged, wins outright on a name conflict, and keeps its configured order ahead of approved populations. `Access::Search`'s two-stage semantics, retry bounds, deduplication, rollback safety, evidence states, and early stop are untouched.
-- `Karst::Access::Search`: after an ordinary bounded sample observes no usable user, Karst now automatically retries each *approved* candidate population in configuration order, stopping at the first verified success. Bounded by `config.population_retry_limit` records per population (default 3, max 10) and by `config.access_sweep_limit` total extra requests. Every approved population is reported, including the ones deliberately not run.
-- `config.population_retry_limit`.
-- Initial project documentation, contributor tooling, and continuous integration.
-- Configuration and an idempotent, deliberately inert `sql.active_record` subscription lifecycle.
-- Automatic subscription after Rails initialization when Karst is enabled.
-- Immutable, minimal SQL events constructed internally from valid `sql.active_record` notifications.
-- Bounded, thread-safe, process-local retention of recent events through `Karst.buffer`.
-- Experimental, conservative SQL canonicalization independent of event capture, preserving structural casts and list cardinality while normalizing supported literals, whitespace, and ordinary comments.
-- Internal deterministic query-shape identity: a SHA-256-based fingerprint over canonicalized SQL, with declared `IN (?+)` placeholder-list arity equivalence, feeding an immutable `Karst::Sql::Shape` that aggregates count, cache hits, duration statistics, and up to three sample events (first, slowest, latest) per shape.
-- `Karst.window`, Karst's first public analysis API: one immutable `Karst::Sql::Window` snapshot per call, derived from exactly one `Karst.buffer.to_a` read and grouped into `shapes` (deterministically ordered by count, then duration, then fingerprint) and `declined` events, with `event_count`, `capacity`, and `saturated` reporting whether older events may already have been evicted from the retained window.
-- `Buffer#capacity`, exposing the fixed capacity of the retained buffer so `Karst.window` can report it.
-- `GET /karst`, a development-only HTTP evidence surface served by a small Rack middleware (no engine, route, or controller) that presents `Karst.enabled?`, `Karst.subscribed?`, and basic `Karst.window` counts. Loopback-only, gated by `Rails.env.development?` at both insertion and request time, and transparent to every other request.
-- `Karst::Spec::Observer`, an opt-in RSpec integration (`require "karst/spec/observer"`) that turns real spec execution into a deterministic JSON scenario catalog: for every example that reaches a browser-facing (HTML) Rails request, it records the request's method, recovered route pattern, controller/action, format, status, and redirect target (with any query string stripped, since redirect targets can carry the same class of secret as request paths), alongside the Warden principal immediately before and after that request and whether it changed -- raw evidence rather than a "setup versus subject" classification, since a single request offers no reliable signal for telling a signup or checkout-completion route that happens to authenticate apart from a login route. Also records the example's stable id, file/line, nested description, and outcome. Built entirely from `ActiveSupport::Notifications` and Warden's public hooks; never parses spec source, route-helper arguments, or FactoryBot calls, and never persists into the host application's database.
-- `Karst::Spec::Catalog`, a read-only index over the JSON artifact `Karst::Spec::Observer` writes, answering `catalog.scenarios_for(controller:, action:, http_method: nil)` from an immutable `Karst::Spec::Scenario` per browser-facing request -- one example that issues several such requests (a denied attempt, then an allowed retry) legitimately produces one Scenario each. Indexed by controller/action, Rails' own stable routing identity, so dynamic id segments never fragment lookup; `http_method` narrows further only when one controller/action answers more than one verb. Loads from `tmp/karst/scenarios.json` by default (or `Rails.root`-relative when Rails is loaded), reports an explicit `:missing`/`:invalid`/`:ready` status so "not yet generated" is never confused with "zero scenarios observed," and skips malformed individual entries rather than failing the whole artifact. `observed_status`/`observed_redirect` name what a spec run observed, not what it asserted; `example_outcome` (`passed`/`failed`/`pending`) keeps a failing example's evidence visible without presenting it as verified. Reuses `Karst::Spec::Principal`'s type/id/scope evidence as-is, reintroduces no setup-versus-subject classification, and requires no RSpec, Rails, or database access to read an already-written artifact. Each Scenario keeps both `principal_before` and `principal_after` rather than collapsing to one side, since a signup or checkout-completion scenario is exactly the case where the identity a request produces is the evidence that matters.
-- Explicit, data-only RSpec scenario names through `karst: "Name"` or `karst: { name: "Name" }` metadata, serialized alongside the existing stable example provenance. Malformed opt-in metadata fails the example with a clear configuration error; unannotated discovery remains unchanged.
-- Ruby 2.7 and Rails 6.1 support, backed by a blocking CI job: `require "karst"`, runtime SQL evidence, the spec observer, the scenario catalog, and `/karst` all work unchanged on that floor. The page-local badge is the one capability that degrades there (Rack 2 cannot safely expose a bufferable response body to rewrite); `/karst` remains directly reachable. See [ARCHITECTURE.md](ARCHITECTURE.md#compatibility-policy).
-- `Karst::Value`, a small internal `Struct`-based immutable value-object helper standing in for Ruby 3.2's `Data.define` across every Karst value object (`Sql::Event`, `Sql::Shape`, `Sql::Window`, `Spec::Principal`, `Spec::RequestObservation`, `Spec::ExampleObservation`, `Spec::Scenario`), used uniformly on every supported Ruby.
-- `Karst::ExecutionContext`, a small internal request-local storage seam used by the page badge and the spec observer: delegates to `ActiveSupport::IsolatedExecutionState` where available, and falls back to a per-thread store on Rails 6.1.
-- `bin/rails generate karst:install`, optional Rails scaffolding for the host-specific seams Karst cannot safely infer: a documented, entirely commented-out `config/initializers/karst.rb` placeholder for every identity hook, a small explicitly named `KarstIdentityController` whose `create` action resolves the submitted principal strictly through `Karst::Identity.resolve` (never a bare `Model.find`, so it can never reach outside the configured `config.principals` scope) before raising `NotImplementedError` with a `TODO` until a developer wires up this application's real authentication against that already-resolved principal, and development-only routes for that controller (idempotent across repeated runs, via Thor's own file-collision handling and a duplicate-safe route insertion). Implements no Devise/Warden/generic authentication mechanism and never runs automatically; existing manual `Karst.configure` setups have no need to run it.
-- `Karst::Access::PrincipalSampler`, an optional candidate-selection step ahead of the experimental access sweep: over an Active Record relation or model class it replaces "first 25 rows" with up to `access_sweep_limit` deterministic principals chosen for database-state diversity rather than whatever happens to sort first -- boolean columns, `enum` columns, nullable-foreign-key presence/absence, and other low-cardinality scalar columns (this is schema-state diversity the sampler observed in the database, not behavioral diversity; it never executes a route). Column candidacy requires an observed cardinality of 10 or fewer (via one bounded `DISTINCT ... LIMIT` query per candidate column, never a full-table scan or `COUNT(*)`), a conservative PII-aware column-name filter that unconditionally excludes anything resembling email, name, phone, address, token, password, or other sensitive fields regardless of cardinality, and a separate name-based exclusion for foreign keys shaped like a tenant/account/organization boundary (`tenant_id`, `account_id`, and similar) -- checked independently of nullability and cardinality, since a *nullable* such column would otherwise reach presence/absence sampling without ever going through the cardinality check. Query volume is bounded by dimension and limit counts, not row count (verified flat between 300 and 8,000 rows in the test suite), and is enforced as a hard invariant at every query-issuing call site via `PrincipalSampler.query_budget(limit)` -- `#call` may return fewer than `limit` principals if the budget is exhausted, but never issues more queries than that budget declares. Never escapes the configured principal scope (an already tenant-scoped relation stays tenant-scoped), and returns each selected principal alongside the minimal evidence (e.g. `"premium=true"`) that earned it a slot. Raises `Karst::Access::PrincipalSampler::UnsupportedPrimaryKey` (a `Karst::Access::Error`) for an Active Record source with a composite or missing primary key, rather than failing obscurely mid-query. Falls back to the existing bounded-first strategy, unchanged, for any non-Active-Record Enumerable source. `/karst` prefers this over "first 25" whenever the configured principal source supports it, purely as a label distinction -- selection, execution, identity assumption, and rollback semantics in `Karst::Access::Sweep` itself are unchanged.
-- `Karst::Access::ResourceEvidence`, a read-only, opt-in follow-up step for one specific `Access::Sweep` outcome: given the exact resource a route addresses and one specific principal, it reports simple, directly observed foreign-key relationships between those two records (e.g. `Document#user_id` pointing at that exact `User#id`) -- evidence, not an authorization claim, and never phrased causally. Only foreign-key-shaped columns (ending in `_id`) are ever inspected, so no other attribute (name, email, token, ...) is read or shown; only a direct column-value comparison between the two given records is made, never a join, a `has_many` traversal, or any multi-hop graph walk. `.for_outcome` additionally resolves the resource from a route path using only Rails' own route recognition plus its controller-to-model naming convention, and only trusts that resolution 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 -- produces a reported limitation rather than a guess. `Result#to_text` renders the plain evidence format (principal, observed status, then related state).
-- Candidate population discovery and curation, an opt-in workflow on top of `config.principal_populations`/`config.principal_sources`. `Karst::Access::PopulationDiscovery` uses Ruby's standard-library Ripper AST parser to list only statically named, zero-argument Rails `scope` declarations made directly in application model source; it never enumerates or invokes arbitrary class methods, executes scope bodies, or issues SQL. Concern-contributed scopes are explicitly outside this initial discovery boundary. Run it via `bin/rails karst:populations` or the `/karst/populations` page (linked from the main panel). The page groups scopes by model, collapsed by default behind native `<details>` (small vanilla JS only powers client-side search/filter -- no frontend framework), stays usable at 150 models/500 scopes, and surfaces the current selection first. `Karst::Access::PopulationPreview` is a separate, explicit, `LIMIT 3`-bounded validation step (never a `COUNT`) for one discovered scope at a time. `Karst::Access::PopulationConfigSnippet` renders a curated selection into copy-pasteable `config.principal_populations`/`config.principal_sources` Ruby -- nesting per source when more than one is involved, so the same population name on two different models stays distinguishable -- and never writes to the host application's files. The main `/karst` panel gains a **Try another population** guided retry, shown only once an analysis found no usable outcome: one button per already-*approved* (configured, not merely discovered) population, running a fresh bounded sweep against just that population, respecting the existing `access_sweep_limit`. When the analysis observed a halted controller callback, approved populations are optionally ranked by `Karst::Access::PopulationSuggestion`, a transparent, no-AI substring-overlap name heuristic that always shows every approved population and never claims the suggested one will change the outcome -- only running it does.
+- Initial release of route-access verification through `/karst`, `bin/rails karst:verify`, and the MCP `verify_access` tool.
+- Bounded sampling of existing users with observed status, redirects, halted callbacks, exceptions, and database writes.
+- Candidate-population discovery, preview, configuration export, and approval through the original population-management workflow and `karst:populations` rake task.
+- Browser **Test as** and **Stop testing as** workflows, a page-local badge on Rack 3, and custom-authentication generator scaffolding.
+- Automatic single-model Devise support, explicit multi-model/custom-authentication configuration, and access-search rollback isolation.
+- The opt-in RSpec observer/catalog/scenario subsystem and inferred resource-relationship evidence.
+- Runtime SQL capture through a bounded buffer and `Karst.window` analysis.
+- Ruby 2.7+ and Rails 6.1+ compatibility.
 
 ### Changed
 
-- Restructured `/karst` around its primary workflow -- "which existing principal can I use to test what I'm looking at" -- rather than giving equal visual weight to route context, spec evidence, access analysis, and raw SQL evidence. A compact route header (method, path, controller/action) replaces the old verbose route form; **Analyze N principals** is the obvious primary action; usable principals and their **Test as** actions remain prominent (per the actionable hierarchy above); a currently-assumed browser identity is now shown as a clear banner exposing **Stop testing as**, worded so it never implies Karst can restore a previous session. Spec evidence and Runtime SQL evidence are unchanged in substance but are now demoted under a collapsed **Diagnostics** section (native `<details>`/`<summary>`, no JavaScript), each summarized by a useful count (e.g. "Spec evidence — 3 matching scenarios", "Runtime SQL — 544 observations · 66 shapes") and expanded only on request; a disabled SQL capture state is called out instead of silently collapsing. Coherent, non-dominating states were added for an unconfigured principal source, unconfigured browser Test-as, and no route selected yet.
-- Reorganized `/karst` access results around a host-configurable usable-outcome presentation policy (2xx by default): usable sampled principals and their Test-as actions are prominent, exact-resource relationship evidence is shown when available, and every other raw outcome remains preserved in a subordinate expandable section. Resource-evidence principal resolution now obeys the configured principal source.
-- Marked configuration, buffer, subscription, and the experimental SQL canonicalizer as private implementation constants.
-- Lowered `required_ruby_version` to `>= 2.7` and the `activesupport` dependency to `>= 6.1, < 9`.
+- Reframed the primary interface around finding an existing user who can reach a selected route.
+- Candidate populations became an automatic second search stage after the ordinary sample found no usable user.
+
+[0.2.0]: https://github.com/chdsbd/karst/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/chdsbd/karst/releases/tag/v0.1.0

data/README.md

@@ -2,6 +2,8 @@
 
 Karst finds a real, existing user who can reach a page in your Rails app — by actually running the route as your users and reporting what happened.
 
+**Why Karst?** Karst terrain hides complex systems beneath the surface. As a Rails codebase grows, its real runtime paths become similarly difficult to see from the surface. The Karst gem reveals what actually happens underneath.
+
 "Which user can access this page?" is normally answered by reading role checks and `before_action` filters by hand, or asking around until someone remembers a working login. Karst answers it by running the real route, through your real Rails request stack, as a bounded set of real users — and shows you the evidence: HTTP status, redirect, halted callback, exception.
 
 ```text
@@ -35,7 +37,7 @@ Open `/karst` in your browser.
 
 Using Devise with one user model? That's usually it — Karst finds it automatically through Devise's own routing metadata, with no configuration. If Karst finds more than one Devise model, it asks you to pick which one(s) to test right there on the `/karst` panel — no initializer, no restart. If it finds none at all, it says so instead of guessing.
 
-Custom or non-Devise authentication needs a few lines of setup — see [Custom authentication](#custom-authentication) below.
+Custom or non-Devise authentication needs a few lines of setup — see [Custom authentication](#custom-authentication) below. Using Rails 8's built-in `bin/rails generate authentication`? See [docs/rails8-authentication.md](docs/rails8-authentication.md) for the exact recipe — Rails' generated authentication has no registry Karst can safely infer from, unlike Devise.
 
 ## How it works
 
@@ -51,10 +53,12 @@ Sometimes the right user is rare and won't show up in a normal recent-user sampl
 
 ```
 No verified usable user found
-Karst found 3 application-defined user groups that could be tried. [ Review candidate groups ]
+Karst found 3 application-defined user groups that could be tried.
 ```
 
-Open `/karst/populations`, check the groups Karst may try (`system_admins`, `auditors`, ...), and press **Approve**. From then on, approved groups are searched automatically — through `/karst`, the CLI, and MCP alike — until one produces a usable user. Approving is a hint, never a claim: Karst only reports that a user was *sampled from* `system_admins`, never that the group is what granted access.
+Select the groups Karst may try (`system_admins`, `auditors`, ...) and press **Approve and rerun** without leaving `/karst`. From then on, approved groups are searched automatically — through `/karst`, the CLI, and MCP alike — until one produces a usable user. Approving is a hint, never a claim: Karst only reports that a user was *sampled from* `system_admins`, never that the group is what granted access.
+
+Approvals are persistent local state. The advanced `/karst/populations` page exists only to inspect and revoke them, including approvals made stale by a renamed scope or changed principal source. It cannot approve new groups; normal route analysis never needs to visit it.
 
 Need populations committed as reviewable code, or applied outside your own machine (CI)? `config.principal_populations` does that and always takes precedence over an approval of the same name — see [docs/advanced-configuration.md](docs/advanced-configuration.md#curating-candidate-populations) for discovery, approval, and precedence details.
 
@@ -68,8 +72,6 @@ For every user it tries, Karst reports:
 - observed database writes
 - which user was tested, and which configured population (if any) produced them
 
-When it can, Karst also shows how the tested user relates to the resource on the page — for example, `Document #22 → user_id → User #27`.
-
 Karst reports observations, not authorization conclusions. If Rails halted at `authorize_admin`, Karst reports that callback name; it does not claim the user lacks permission unless your application says so itself.
 
 ## CLI
@@ -83,7 +85,15 @@ Runs the same search as `/karst` from a shell. Exit code `0` means a usable user
 
 ## Coding agents
 
+MCP support is optional. Add its runtime dependency to your application's
+Gemfile and install it before starting the server:
+
+```ruby
+gem "mcp", "~> 0.9.0"
+```
+
 ```bash
+bundle install
 bin/rails karst:mcp
 ```
 
@@ -99,7 +109,7 @@ Claude Code or another [MCP](https://modelcontextprotocol.io) client can call `v
 
 ## Configuration
 
-Usually, you don't. A conventional Devise app needs no initializer at all: the user model comes from Devise's own routing metadata, sampling states come from your schema, and candidate populations are approved at `/karst/populations` rather than written down.
+Usually, you don't. A conventional Devise app needs no initializer at all: the user model comes from Devise's own routing metadata, sampling states come from your schema, and candidate populations are approved inline after a failed analysis rather than written down.
 
 The one option worth knowing is the off switch:
 
@@ -123,11 +133,13 @@ Karst.configure do |config|
 end
 ```
 
-The compatibility-preserving `bin/rails generate karst:install` command optionally scaffolds this custom-authentication escape hatch. Replace its `TODO`s with your app's real sign-in/sign-out code. A conventional single-model Devise app needs none of its initializer, controller, or routes. Browser **Test as** needs a second, similar pair of hooks (`config.assume_browser_identity` / `config.clear_browser_identity`) — see [docs/advanced-configuration.md](docs/advanced-configuration.md).
+The `bin/rails generate karst:install` command optionally scaffolds this custom-authentication escape hatch. Replace its `TODO`s with your app's real sign-in/sign-out code. A conventional single-model Devise app needs none of its initializer, controller, or routes. Browser **Test as** needs a second, similar pair of hooks (`config.assume_browser_identity` / `config.clear_browser_identity`) — see [docs/advanced-configuration.md](docs/advanced-configuration.md).
+
+Using Rails 8's own `bin/rails generate authentication` instead of Devise? [docs/rails8-authentication.md](docs/rails8-authentication.md) is the same escape hatch, filled in with that generator's own `User`/`Session`/`Current` objects.
 
 ## Safety
 
-Karst is for local development only — `/karst`, the badge, and Test As only work from loopback requests while `Rails.env.development?` is true. Every search is bounded (25 users by default, 100 max), and every probe runs inside a database transaction Karst rolls back.
+Karst is for local development only — `/karst`, the badge, and Test As only work from loopback requests while `Rails.env.development?` is true. The ordinary sample is bounded to 25 users by default (100 max). If it finds no usable user, approved candidate populations can add a separate bounded retry stage. Every probe runs inside a database transaction Karst rolls back.
 
 That rollback only covers writes made through the same Active Record connection. Jobs, mail, external HTTP calls, files, Redis, and other database connections aren't covered — a route that triggers those can still cause real side effects even though its own database writes are undone.
 

data/SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Supported versions
 
-Karst has not released a supported version yet. This policy will be updated when releases begin.
+The latest released version of Karst receives security fixes. Older prerelease and early versions may not receive fixes; users should upgrade to the latest release.
 
 ## Reporting a vulnerability
 

data/docs/advanced-configuration.md

@@ -6,6 +6,8 @@ If you are looking for an option that used to be here, check [Removed configurat
 
 ## Custom or non-Devise authentication
 
+Using Rails 8's own `bin/rails generate authentication` rather than Devise? See [rails8-authentication.md](rails8-authentication.md) for the exact, complete recipe — it is an instance of the same escape hatch documented below, filled in with that generator's own `User`/`Session`/`Current` objects. Karst has no registry to infer this from the way it does for Devise, so it needs the few lines below rather than nothing.
+
 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
@@ -23,7 +25,7 @@ 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.
+`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 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:
 
@@ -113,23 +115,20 @@ When the right user is too rare for this to reach — a role held by three peopl
 
 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.
+**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. 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`:
+**Approval.** When an analysis finds no usable user and unapproved candidates exist, `/karst` offers those candidates in the failed result. Pressing **Approve and rerun** persists the checked selection to `tmp/karst/approved_populations.json`, relative to `Rails.root`, and repeats that same route analysis:
 
 ```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.
+Deliberately machine-local, git-ignored development state, not project configuration, 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.
 
-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.
+**Revocation.** The advanced `/karst/populations` surface lists only approvals already stored, marks approvals that current discovery or principal-source configuration no longer confirms, and revokes one exact entry at a time. It cannot discover or approve groups. This narrow page remains because stale approvals may no longer appear in any failed route result, while persistent local state must always have a safe removal path.
 
-## Resource evidence
+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.
 
-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
 

data/docs/rails8-authentication.md

@@ -0,0 +1,171 @@
+# Rails 8 generated authentication
+
+`bin/rails generate authentication` (new in Rails 8) scaffolds a plain
+`User`/`Session` pair, an `ActiveSupport::CurrentAttributes` `Current` class,
+and an `Authentication` concern that resumes a session from a signed,
+permanent `session_id` cookie. It is not Devise, and it registers itself
+nowhere Karst can safely discover: Devise's zero-config path exists only
+because `Devise.mappings` is public, framework-owned metadata Devise itself
+already relies on for `current_user`/`authenticate_user!`. Rails' generated
+authentication has no equivalent registry — there is no framework-provided
+list of "the models this app authenticates" or "the concern doing it" for
+Karst to read. Guessing from column names (`password_digest`), class names
+(`User`, `Session`, `Current`), or `ApplicationController`'s ancestry would
+be exactly the kind of heuristic inference Karst deliberately never does for
+custom authentication (see [Custom or non-Devise
+authentication](advanced-configuration.md#custom-or-non-devise-authentication)).
+So this is a small, explicit recipe instead of a one-liner — five short
+`Karst.configure` blocks below cover the whole thing, using this
+application's own generated `User`, `Session`, and `Authentication`
+concern exactly as the generator created them. Nothing here monkey-patches
+`Current`, `Session`, or any generated controller.
+
+This is the *complete* minimum configuration; nothing else is required.
+
+## 1. Principal source
+
+```ruby
+Karst.configure do |config|
+  config.principals = -> { User.all }
+end
+```
+
+## 2. Probe identity: sign a probe session in
+
+Karst's access search runs each probe through an isolated
+`ActionDispatch::Integration::Session`, inside a database transaction Karst
+always rolls back — so the cleanest way to sign a probe in is the same way
+a real user signs in: create a `Session` row and let the real
+`Authentication` concern resume it. Run `bin/rails generate karst:install`
+to scaffold the controller and development-only routes (the generator is
+authentication-agnostic; it works the same regardless of what identity
+system fills in its `TODO`s). Replace the *entire body* of the generated
+`app/controllers/karst_identity_controller.rb` -- not just its `TODO`s --
+with the code below; the generator's own template raises
+`NotImplementedError` and has no knowledge of this application's generated
+`Authentication` concern:
+
+```ruby
+# app/controllers/karst_identity_controller.rb
+class KarstIdentityController < ApplicationController
+  allow_unauthenticated_access only: :create
+  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
+
+    start_new_session_for(principal) # from this app's own Authentication concern
+    head :no_content
+  end
+
+  def destroy
+    terminate_session # from this app's own Authentication concern
+    head :no_content
+  end
+end
+```
+
+`start_new_session_for`/`terminate_session` are the exact private helpers
+the Rails 8 generator already put in `app/controllers/concerns/authentication.rb`
+— this controller calls them, it does not reimplement them. `only: :create`
+mirrors the generated `SessionsController`'s own
+`allow_unauthenticated_access only: %i[new create]`: signing a probe in must
+skip `require_authentication` (nothing is authenticated yet), but signing
+one out does not need to, exactly like a real user's logout.
+
+```ruby
+Karst.configure do |config|
+  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
+end
+```
+
+## 3. Probe identity: clear it
+
+```ruby
+Karst.configure do |config|
+  config.clear_identity = ->(session) { session.delete "/karst_test_logout" }
+end
+```
+
+Karst always calls this after a probe, including when the route being
+tested raises — so a probe's `Session` row is created and destroyed inside
+the same rollback-only transaction as everything else it does. No probe
+identity ever outlives its own analysis. See [the "database writes
+observed" note](#note-database-writes-observed-is-honest-not-zero) below
+for the one visible side effect of this being a *real* database write,
+even though it never persists.
+
+## 4. Browser Test As
+
+Test As mutates the developer's real browser session directly, not through
+a sub-request — so it sets the same signed cookie
+`start_new_session_for` sets, using a real `Session` row:
+
+```ruby
+Karst.configure do |config|
+  config.assume_browser_identity = lambda do |request, principal|
+    rails_request = ActionDispatch::Request.new(request.env)
+    probe_session = principal.sessions.create!(user_agent: "Karst Test As", ip_address: "127.0.0.1")
+    rails_request.cookie_jar.signed.permanent[:session_id] =
+      { value: probe_session.id, httponly: true, same_site: :lax }
+  end
+end
+```
+
+`request` here is a bare `Rack::Request` (Karst serves `/karst` at the Rack
+boundary, before Action Controller) — wrapping its `env` in
+`ActionDispatch::Request` is ordinary Rack request-object adaptation, not a
+patch to any Rails class, and gives access to the same signed `cookie_jar`
+a real controller's `cookies.signed` uses. Because `ActionDispatch::Cookies`
+sits above Karst's middleware in the stack, the `Set-Cookie` header this
+produces is flushed on the way back out exactly like it would be for a real
+controller action.
+
+## 5. Stop Testing As
+
+```ruby
+Karst.configure do |config|
+  config.clear_browser_identity = lambda do |request|
+    rails_request = ActionDispatch::Request.new(request.env)
+    Session.find_by(id: rails_request.cookie_jar.signed[:session_id])&.destroy
+    rails_request.cookie_jar.delete(:session_id)
+  end
+end
+```
+
+This is the whole recipe. There is no sixth step, and nothing above reaches
+into `Current`, `Session`, or a generated controller's internals —
+`start_new_session_for`/`terminate_session` are called as the application's
+own public-to-its-subclasses methods, exactly as a real controller action
+would call them.
+
+## Note: "database writes observed" is honest, not zero
+
+Devise/Warden's Test As and the plain `session[:user_id] = ...` custom-auth
+example are memory-only: neither ever performs a database write to sign a
+probe in or out, so a route with no writes of its own reports "Database
+writes observed: 0". Rails' generated authentication persists a `Session`
+row per sign-in, so every probe under this recipe legitimately shows **2**
+observed writes (the login `INSERT` and the logout `DELETE`) even when the
+route itself never touches the database. This is not a bug and not
+something to suppress: Karst reports what actually happened, and an insert
++ delete genuinely happened. It does mean write-count evidence from this
+recipe is not directly comparable to a Devise/Warden or memory-only
+custom-auth analysis of the same route — a "2 writes observed" result here
+can mean only Karst's own probe login/logout wrote anything.
+
+## Acceptance test
+
+[`spec/integration/rails8_auth_golden_path_integration_spec.rb`](../spec/integration/rails8_auth_golden_path_integration_spec.rb)
+boots a real `Rails::Application` using exactly this recipe against a
+fixture that reproduces the Rails 8 generator's own files
+([`spec/support/rails8_auth_application.rb`](../spec/support/rails8_auth_application.rb)),
+with an ordinary user population and one rare privileged user, a restricted
+route, a real access search, candidate-population discovery/approval, Test
+As, Stop Testing As, and an assertion that no row is left behind afterward.
+It runs against the real `rails ~> 8.0.0` gemfile
+([`gemfiles/rails_8_0.gemfile`](../gemfiles/rails_8_0.gemfile)) in CI.