karst 0.1.0 → 0.4.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
 
@@ -45,16 +47,35 @@ Custom or non-Devise authentication needs a few lines of setup — see [Custom a
 4. Every result shows what actually happened: status, redirect, halted callback, exception, and observed database writes.
 5. Found a usable user? Click **Test as** to become them in your own browser and keep working.
 
+## Working with an existing record
+
+**Karst runs against records already in your development database, however they got there.** Console, seeds, `db:fixtures:load`, FactoryBot run in development/console, your app's own UI, or a tool like Body Double — Karst doesn't care how they were created, and doesn't require Body Double specifically.
+
+That's true of the *path* unconditionally — `/admin/imports/123` is just a string, and any row backing it is fair game. It's true of *identity* only within a boundary: to run a probe as a specific principal (`--as`, or **Test as** on the panel), that record must be one Karst's configured principal source(s) can actually resolve (see [Identity.resolve](docs/advanced-configuration.md#running-as-a-specific-principal)) — an arbitrary development-database row is not automatically assumable as a principal just because it exists.
+
+What Karst does *not* do is start from an object and find routes for you — you still bring the path. The workflow is:
+
+1. **Know a concrete path** — `/admin/imports/123`, from your own knowledge of the app.
+2. **Verify it** — `bin/rails karst:verify GET /admin/imports/123`, or press **Who can use this?** at `/karst`.
+3. **Optionally run as a specific user** — `--as User:72` on the CLI (see [CLI](#cli) below), or **Test as** on the panel once a usable user is found.
+4. **The panel/badge workflow** — every page in development carries a **Karst** badge linking straight to `/karst?controller=...&action=...`, already scoped to what rendered it.
+
+One caveat worth being explicit about: a record created and then rolled back *inside a transactional test spec* never reaches the development database at all, so there's nothing there for Karst to run against. Data loaded into the development database itself — by any of the mechanisms above — is what "existing record" means here.
+
+Karst does not claim to find every route a given user can reach, does not claim to prove nobody else can reach a route, and does not start a search from an arbitrary object. It runs the one route you name, using either Karst's sampled identity or the explicit principal you select, and reports what it observed.
+
 ## Candidate populations
 
 Sometimes the right user is rare and won't show up in a normal recent-user sample. Karst can find these groups itself — no configuration needed. When the ordinary sample comes up empty, `/karst` says so:
 
 ```
 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 +89,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
@@ -81,9 +100,89 @@ bin/rails karst:verify GET /admin/imports/123 --json
 
 Runs the same search as `/karst` from a shell. Exit code `0` means a usable user was found, `1` means the search completed without one, `2` means a setup error. The `--json` form is a stable, schema-versioned evidence document meant for scripts and tools.
 
+The terminal output answers the access question first, in a few lines however many users were tested:
+
+```text
+Sample: 50 users tested, 1 verified usable
+  42  403 Forbidden · halted at require_admin
+   6  302 Found → http://localhost:3000/suspended · halted at require_active
+        User #3, User #9, User #14, +3 more
+   1  exception NoMethodError
+        User #31
+   1  200 OK · verified usable
+        User #27
+  identity: 50 confirmed
+```
+
+Each line is one observed outcome and how many users observed it, largest first. Users who observed the same response — same status, redirect, halted callback, exception, dispatched action, and database writes — are one outcome, however long each request took. Users are named, a few at a time, for every outcome except a single largest one; `--json` lists every user under every outcome.
+
+Already know which existing record you want to test as — from the console, a seed, `db:fixtures:load`, or your app's own UI? Skip sampling and name it directly:
+
+```bash
+bin/rails karst:verify GET /admin/imports/123 --as User:72
+```
+
+`--as MODEL:ID` resolves that record through Karst's own configured principal source (the same lookup the panel's **Test as** button uses) and runs the route as exactly that principal — never a bespoke `constantize`/`find`, so a record outside your configured source(s) simply won't resolve. It's human-only: neither `verify_access` nor `reproduce_request` over MCP accepts it, and an agent can never pick a principal through Karst.
+
+## Reproducing a request
+
+Sometimes the question isn't "who can reach this page" but "something calls
+this endpoint — what request do I send to exercise the same behavior?".
+
+Karst answers that the same way: it issues **one** request through your real
+application, inside a rolled-back transaction, and reports what happened —
+plus a cURL command for exactly what it sent.
+
+```bash
+bin/rails karst:reproduce POST /api/v1/inspections \
+  --content-type application/json \
+  --body '{"serial_number":"ABC123","status":"passed"}'
+```
+
+```text
+Observed execution
+  Api::V1::InspectionsController#create
+  halted at authenticate_api_key!
+
+Observed response
+  401 text/html
+
+Observed effects
+  0 database writes (rollback attempted on the same connection)
+
+Reproduce
+  curl -X POST 'http://localhost:3000/api/v1/inspections' \
+    -H 'Content-Type: application/json' \
+    -d '{
+    "serial_number": "ABC123",
+    "status": "passed"
+  }'
+```
+
+That halted callback is the endpoint's real gate — observed, not inferred from
+reading the controller. Add the credential it wants, send again, and the cURL
+you copy is one you have watched work.
+
+`karst:reproduce` takes the same `--as MODEL:ID` as `karst:verify` above, to send that one request as a specific existing record instead of the ordinary sampled one.
+
+Secrets never come back out. Parameters go through your app's own
+`config.filter_parameters`, and credential-bearing headers become placeholders
+like `<API_KEY>` without their values ever being read. The same thing is
+available at `/karst` under **Reproduce request**, and to agents as the
+`reproduce_request` MCP tool. See
+[docs/request-reproduction.md](docs/request-reproduction.md).
+
 ## 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", ">= 1.5.0", "< 1.7"
+```
+
 ```bash
+bundle install
 bin/rails karst:mcp
 ```
 
@@ -95,11 +194,32 @@ bin/rails karst:mcp
 }
 ```
 
-Claude Code or another [MCP](https://modelcontextprotocol.io) client can call `verify_access` and get back exactly the evidence `karst:verify --json` prints. An agent can guess who *should* have access by reading code; only Karst can show who actually does. The agent picks the path and method — it can't choose a user, skip the rollback, or use Test As.
+Claude Code or another [MCP](https://modelcontextprotocol.io) client gets two tools:
+
+- `verify_access` — exactly the evidence `karst:verify --json` prints. An agent can guess who *should* have access by reading code; only Karst can show who actually does.
+- `reproduce_request` — exactly the evidence `karst:reproduce --json` prints, including the redacted cURL command. It permits `GET` and `HEAD` by default; mutating methods fail closed before an application request is executed.
+
+In both cases the agent picks the request — it can't choose a user, skip the rollback, raise a limit, or use Test As. That includes `--as`: it's a CLI-only, human-only option (see [CLI](#cli) above), and neither MCP tool accepts it in any form.
+
+Human-driven `bin/rails karst:reproduce` and `/karst` reproduction retain
+explicit `POST`, `PUT`, `PATCH`, and `DELETE` support. A host that deliberately
+wants to give an MCP client the same mutating capability must opt in:
+
+```ruby
+Karst.configure { |config| config.mcp_mutating_requests = true }
+```
+
+This permits real application requests; it does not make them side-effect-free.
+Karst only attempts rollback for database work on the request's own connection.
+Jobs, email, outbound HTTP, files, Redis/external stores, other database
+connections, and other non-transactional effects remain possible. See
+[request reproduction](docs/request-reproduction.md#from-a-coding-agent).
+
+`bin/rails karst:mcp` requires the `mcp` gem to satisfy `>= 1.5.0, < 1.7` — the 1.5 and 1.6 series, which Karst is tested against. If your application already depends on `mcp` at a version outside that range (directly, or through another gem), `karst:mcp` names the version it found and the range it needs; constrain `mcp` in your Gemfile as shown above and run `bundle update mcp` to resolve it.
 
 ## 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:
 
@@ -120,17 +240,25 @@ Karst.configure do |config|
     session.post "/karst_test_login", params: { account_id: account.id }
   end
   config.clear_identity = ->(session) { session.delete "/karst_test_logout" }
+  # How Karst sees which account the app itself actually ran as:
+  config.observe_identity = ->(context) { context.controller&.current_account }
 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).
+That last hook is what lets Karst prove a result rather than assume it. Devise applications need no equivalent — Karst reads the application's own Warden session. Without either, Karst reports identity as *unobservable* instead of claiming a request ran as the user it was asked to run as. See [Runtime-confirmed identity](docs/advanced-configuration.md#runtime-confirmed-identity).
+
+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.
 
+Access analysis is GET-only, and stays that way: running a mutating method as 25 users would mean 25 real creates. [Request reproduction](docs/request-reproduction.md) is the one place a non-GET request is issued, always exactly once and always because you asked for it.
+
 ## Compatibility
 
 Ruby 2.7+, Rails 6.1+. Every core capability (`/karst`, CLI, MCP, access search) works across that whole range; the page-local badge needs Rack 3 (Rails 7.1+) and is simply absent on Rails 6.1/7.0 — `/karst` itself is unaffected. See [ARCHITECTURE.md](ARCHITECTURE.md#compatibility-policy) for the CI-backed matrix.

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

@@ -4,8 +4,28 @@ Almost nothing here is part of installing Karst. A conventional single-model Dev
 
 If you are looking for an option that used to be here, check [Removed configuration](#removed-configuration) at the end.
 
+## Mutating MCP reproduction
+
+The MCP `reproduce_request` tool permits only `GET` and `HEAD` by default.
+Human-driven reproduction through `bin/rails karst:reproduce` and `/karst`
+still supports explicit mutating methods. To grant that capability to MCP as
+well, the host application must opt in:
+
+```ruby
+Karst.configure { |config| config.mcp_mutating_requests = true }
+```
+
+Without the opt-in, every other method is refused before an application
+request is constructed or executed. With it, MCP may issue `POST`, `PUT`,
+`PATCH`, and `DELETE` under Karst's normal reproduction constraints. Database
+rollback is same-connection best effort, not general side-effect isolation:
+outbound HTTP, email, jobs, files, Redis/external stores, writes through other
+database connections, and other non-transactional effects can still occur.
+
 ## 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
@@ -21,9 +41,19 @@ Karst.configure do |config|
 end
 ```
 
+Then tell Karst how to see which principal the application itself ended up running as. Without this, Karst reports identity as *unobservable* for a non-Devise application rather than assuming its requested identity was the one that ran:
+
+```ruby
+Karst.configure do |config|
+  config.observe_identity = ->(context) { context.controller&.current_account }
+end
+```
+
+See [Runtime-confirmed identity](#runtime-confirmed-identity) below for what Karst does with it.
+
 `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:
 
@@ -42,6 +72,75 @@ When both are configured, every usable user in the results gets a **Test as** bu
 
 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.
 
+## Runtime-confirmed identity
+
+Asking Karst to run a request as `User #123` is not evidence that the request ran as `User #123`. Karst keeps the two apart, on every outcome:
+
+| | What it is |
+| --- | --- |
+| **requested** | The identity Karst was asked to execute as. Intent. `nil` for an anonymous probe. |
+| **established** | What Karst's own identity seam managed to set up. Setup, never evidence. |
+| **observed** | The principal the Rails application itself resolved while running the request. Evidence. |
+
+`identity.confirmation` is the only field that says whether a principal claim about a request is true, and it fails closed:
+
+| `confirmation` | Meaning |
+| --- | --- |
+| `confirmed` | A principal was requested, and the application resolved that same one. |
+| `confirmed_anonymous` | An anonymous probe was requested, and the application resolved no principal. |
+| `absent` | A principal was requested; the application resolved none. The request did **not** run as that user. |
+| `mismatch` | The application resolved a *different* principal than the one requested. |
+| `contaminated` | An anonymous probe was requested, and the application resolved a principal anyway. The probe is invalid, not anonymous. |
+| `unobservable` | Karst could not determine which identity the application used. Nothing may be concluded. |
+
+Only `confirmed` and `confirmed_anonymous` are evidence about identity.
+
+Where the observation comes from:
+
+- **Devise/Warden**: nothing to configure. Karst reads the application's own Warden proxy from the probe request — the same object Devise's `current_<scope>` helper returns — through Warden's public `Proxy#user`, which deserializes an existing session and never runs authentication strategies.
+- **Anything else**: `config.observe_identity`, a callable given one context object (`#controller`, `#request`, `#env`) and returning the application's runtime principal, or `nil` when it resolved none. `controller` is the exact `ActionController` instance that processed the request — Rails sets it on the request env before any callback runs, so it is available even for a request a `before_action` halted.
+- **Neither**: `unobservable`. Karst never falls back to the requested identity.
+
+Timing matters: when an access callback halts the request, Karst observes identity *at that halt* — the state the application had established when the access decision was made — rather than after the request unwound. `identity.observed_at` says which moment an observation came from, and `identity.changed_during_request` is true when the identity the application ended with differs from the one the decision was made with.
+
+This is also what makes authentication and authorization separable. A route gated by `authorize_admin` produces three different observations that mean three different things:
+
+```
+anonymous          observed none      halted at authorize_admin
+ordinary user      observed User #4   halted at authorize_admin
+admin user         observed User #2   200 OK
+```
+
+The first says the gate participates in authentication; the second that it imposes an authorization condition on an identity that *was* correctly established. Karst reports the observations, and does not itself conclude either.
+
+### Anonymous probes
+
+An anonymous probe is a probe in its own right, not the absence of one:
+
+```bash
+bin/rails karst:verify --anonymous /admin/imports/123
+```
+
+or, over MCP, `verify_access(path:, identity: "anonymous")`. Karst establishes no identity, drops any identity queued for the probe session, runs the application's own `clear_identity` hook when one is configured, and then verifies at runtime that the application really did see no principal. If stale state produces one anyway, the result is `contaminated` — never "anonymous". An anonymous probe needs no principal source at all, so it works in an application Karst could not otherwise test.
+
+### Running as a specific principal
+
+`karst:verify` and `karst:reproduce` both accept `--as MODEL:ID`, a human-only way to run as one already-existing record instead of a sampled one:
+
+```bash
+bin/rails karst:verify GET /admin/imports/123 --as User:72
+bin/rails karst:reproduce GET /admin/imports/123 --as User:72
+```
+
+`MODEL:ID` is resolved exclusively through `Identity.resolve` — the same lookup the `/karst` panel's own **Test as** button already uses (see `Karst::Web::BrowserIdentity#assume`). It tries each configured principal source in turn and only ever runs a scoped query (or, for a plain Array/Enumerable source, an in-memory comparison) against that source's own records; a model name or id that does not belong to any configured source simply resolves to nothing. There is no `constantize`/`find` fallback and no way to reach a record Karst wasn't already configured to consider.
+
+A few things this deliberately is not:
+
+- It cannot be combined with `--anonymous` — one request has exactly one identity, requested one way.
+- It never falls back to sampling or to anonymous when the reference doesn't resolve; an explicit `--as` that fails to resolve is a hard, structured error (`error.type: "input_error"`).
+- It is not available over MCP. Neither `verify_access` nor `reproduce_request` accepts a principal argument in any form — an agent can choose *what* to request, never *who* to request it as. This is the same boundary that keeps Test As out of MCP.
+- It does not turn an object into a route. You still bring the concrete path; Karst still only runs the one route you name.
+
 ## Authentication identifiers in local human output
 
 Without `config.principal_label`, Karst normally labels a principal `Model #id`.
@@ -113,23 +212,28 @@ 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.
+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.
+
+**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.
 
 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.
+## When configuration is read
+
+Working out the effective principal sources is real work: reading the local approval and selection files, parsing model source with `Ripper`, and calling your `principals`/`principal_sources` callables. Karst does it **once per resolution**, and reuses that one result for everything else the same resolution answers — setup checks, sampling, population retries, `--as` lookup, **Test as** availability for every listed user, and (on `/karst`) discovering candidate populations to suggest. Within one resolution, each principal source callable is called once.
+
+Reading `bin/rails karst:verify`, an MCP `verify_access` call, and an ordinary `/karst` analysis each take exactly one resolution. **Approving a population is the one operation that takes two**: validating the submission needs the effective sources *before* the write (to confirm what was submitted is still real), and the render that follows needs them fresh *after* the write, so the approval just saved is reflected rather than the state from before it. Each of those two resolutions is still itself one file read and one parse, never repeated within itself.
 
-## Resource evidence
+Nothing is cached beyond one resolution. The next operation reads everything again, so an approval revoked at `/karst/populations`, a scope deleted from a model, or a changed initializer takes effect on the next analysis without restarting the server. Callables that run per request by design — `assume_identity`, `clear_identity`, `observe_identity`, `principal_label` — and `usable_access_outcome`, which is applied to each outcome, are unaffected.
 
-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
 
@@ -149,6 +253,7 @@ The single switch that turns Karst's whole development surface off — `/karst`,
 | --- | --- |
 | `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 |
+| `observe_identity` | Observing which principal the application actually ran as, for non-Devise authentication ([above](#runtime-confirmed-identity)) |
 | `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)) |

data/docs/rails8-authentication.md

@@ -0,0 +1,191 @@
+# 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 — six 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. Runtime-confirmed identity
+
+Karst reports which principal the *application* resolved, not the one it was
+asked to run as. The generated `Authentication` concern resolves exactly that
+into `Current.user`, so the whole observation is one line:
+
+```ruby
+Karst.configure do |config|
+  config.observe_identity = ->(_context) { Current.user }
+end
+```
+
+`Current` is request-local and reset by Rails' own executor between requests,
+so reading it after the probe request is reading that request's own resolved
+identity. A probe whose identity the application never established is then
+reported as `absent` rather than as the requested user having reached the
+route; an anonymous probe (`bin/rails karst:verify --anonymous`) is confirmed
+anonymous only when `Current.user` really was nil. See [Runtime-confirmed
+identity](advanced-configuration.md#runtime-confirmed-identity).
+
+## 5. 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.
+
+## 6. 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 seventh 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.