karst 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c8a746d264f980f133db4f4e60538708b4323b3cdbbbfb0689ce82278bd0cce
-  data.tar.gz: 8060e9f4c93bdf891a2a19fb1195df8d3a2900ddda983bf8230117c1a1bec569
+  metadata.gz: 513a3fddea6f4ffa3b738ec37e53fd3b21ad39efb5f0f7997efb926cf9acfe37
+  data.tar.gz: 22608af3514ea1172109a1ab746ef8a7c76059dae2ef212159d4567ba90025bb
 SHA512:
-  metadata.gz: ecced3eecbac561c88edb885f3eded09fa4d4cc67a3ec61e557ed4d27ef684e02c216009d2d503dbc2ec6cb69b56f379f75b37104d98cadc2eb553827bc7ba93
-  data.tar.gz: 4c71f5045b65849961c6490720a6535ab337157540a8c689a14474c66d228fdb42b95867813741df0aacf81726d4c111be78b124554a678e3cd9075d79e67752
+  metadata.gz: 12ff6ed9b797cd6c8cf4856c3eb95ace456211d9c73dd5f769696d308e8b23da9885823250727f6bf8dace8b3b8c6d5cbb8e90baab59390fc9ac18abd7cf75a2
+  data.tar.gz: f856fbd9d25cea5b4da16aa0ee0764346f29c9faaa104b9073489c4e3aef986a35680ffb5e435270c8945d3878727259fad3956783f224ca484c2b3aa10a47cc

data/ARCHITECTURE.md

@@ -9,6 +9,11 @@ This document describes how Karst is put together and the policy that governs wh
 - `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::Identity::Observer` / `Identity::EvidenceBuilder` / `Access::IdentityProbe` / `Access::ObservedEndpoint` — the runtime-identity seam, which exists to keep three things that are constantly confused apart: the identity Karst was *asked* to run as (intent), the one its own seam *established* (setup), and the one the Rails application itself *observed* while running the request (evidence). `Observer` reads the latter from the probe request's own env — through `config.observe_identity` when configured, otherwise the application's own Warden proxy via Warden's public `Proxy#user`, which deserializes an existing session and never runs strategies — and fails closed to "unobservable" when neither is available, rather than echoing the requested identity back. `ObservedEndpoint` wraps the probe endpoint for exactly one request so Karst holds that request's live Rack env, which is what makes *halt-time* observation possible: Rails puts the dispatching controller on the env before any callback runs, so the identity the application had established when an access callback halted the request is observable at that moment, not merely after the request unwound. `IdentityProbe` owns one probe's whole identity lifecycle and deliberately never raises out of establishment or release — a probe whose identity could not be established is exactly the probe whose runtime observation matters most. `EvidenceBuilder` turns the observations into one `Identity::Evidence`, whose `confirmation` is the only field a machine consumer may read to decide whether a principal claim is true. `Reproduction::Exercise` (below) reuses this same seam rather than maintaining a second identity implementation.
+- `Karst::Reproduction::Exercise` / `Observation` / `Sanitizer` / `Curl` — request reproduction: "something calls this endpoint, what request exercises the same behavior?". `Exercise` issues **exactly one** caller-specified request through the same `Access::ProbeApplication` endpoint and the same same-connection rollback `Access::Sweep` uses, and drives the request's identity through the identical `Access::IdentityProbe` lifecycle `Access::Sweep` uses — requested, established, runtime-observed (captured at `halted_callback` and again at request completion, with halt-time evidence preferred for the reported `identity`, exactly as `Access::Sweep` prefers it for its access decision), confirmed, released — so a reproduced request's `identity` document is a `Karst::Identity::Evidence`, never a bare echo of the identity Karst was asked to send. `Exercise` reports only what it observed -- the controller/action that actually dispatched, the router's own `path_parameters`, the halted callback, the response, the write count. Deliberately not `Access::Sweep` with the GET restriction lifted: a sweep runs one route as up to 25 users, so a mutating method there would mean 25 real creates, 25 enqueued jobs, and 25 delivered mails; `Sweep` stays GET-only and reproduction's blast radius stays one always-explicitly-asked-for request. Anything `Exercise` could not observe is `nil` and named in `Observation#unobserved` rather than inferred from routes, controller source, or strong parameters. `Sanitizer` is the single redaction boundary: it builds an `ActiveSupport::ParameterFilter` from *the reproduced application's own* `config.filter_parameters` (never `Rails.application`, so one application's rules can never filter another's parameters) and applies one conservative credential-name net on top of that result, never instead of it; headers are decided by name alone, so a credential header's value is never read, compared, or echoed. `Referer` and `Origin` are the one exception -- their *value* is a URL, not a credential, so it is parsed and stripped to scheme/host/path (query, fragment, userinfo discarded) rather than judged by name; a value that does not parse as a URL is masked outright. `Access::Probe`'s own redirect sanitization strips a redirect's query string and fragment the same way, for the same reason. `Curl` renders one `Observation` as a runnable command containing exactly what Karst sent -- never a header or credential invented to make the command look complete. `Karst::CLI::Reproduction` is the one adapter over all of it, shared verbatim by `bin/rails karst:reproduce`, the MCP `reproduce_request` tool, and the `/karst` panel, so no surface can show a recipe another would not; its identity serialization is the same one `Karst::CLI::Verification` uses, so the two schemas describe identity evidence identically.
+- `Karst::Access::OutcomeGroups` — the single definition of "these probes observed the same thing", shared by `Access::Result#groups`, the CLI/MCP evidence document, the human CLI summary (`Karst::CLI::OutcomeSummary`), and the `/karst` panel. The key is every observed fact about the request (`SEMANTIC_FIELDS`: status, redirect, exception, halted callback, dispatched controller/action, body marker, writes, rollback) plus the configured `usable_access_outcome` verdict; everything about the probe that made it (`PROBE_METADATA`: requested principal, identity evidence, sampling reasons, elapsed time) is excluded, so equivalent outcomes are never split by timing or identity and distinct ones are never merged. Groups are ordered largest first with a deterministic tie-break over the key itself. A spec requires every `Access::Outcome` field to be classified as one or the other.
+- `Karst::Identity::Snapshot` — one high-level operation's view of the effective identity configuration (principal sources with approvals and selections folded in, setup readiness, browser Test As support), taken once from a single `Configuration#principal_sources` resolution and passed down explicitly, never cached beyond that resolution. Each resolution's `PrincipalSource` copies evaluate their records callable at most once (`PrincipalSource#evaluated_once`). `CLI::Verification` takes one per run. `Web::Middleware` takes one per `/karst` request, after any local-state write that request makes -- reusing the same already-loaded `PopulationApprovals::Record` and `PopulationDiscovery` instance for whatever else that request resolves, including discovering candidate populations to suggest when the sample found nothing usable (`Web::Middleware#inline_population_candidates`). Approving a population is the one request that necessarily takes two resolutions -- pre-write validation, then the post-write render -- each still exactly one file read and one parse (`Web::Middleware#inline_population_approval_result`; see "When configuration is read" in [docs/advanced-configuration.md](docs/advanced-configuration.md#when-configuration-is-read)).
+- `Karst::Access::LocalPath` — the single definition of "a local application path Karst may execute", used by both `Access::Sweep` and `Reproduction::Exercise`. A security check duplicated per caller is a security check that eventually diverges.
 - `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.
 
 Each area is deliberately narrow and composable; none of them depends on the others' internals beyond the public objects listed above.
@@ -51,6 +56,6 @@ Compatibility decisions live behind exactly two narrow seams — `Karst::Value`
 ### CI
 
 - `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.
+- `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, and Rails 7.2, 8.0, and 8.1 on Ruby 3.3. Every row is a required, blocking job. Each row also runs the Devise, multi-Devise, custom-authentication, and Rails-generated-authentication golden paths in isolated processes.
 
 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

@@ -5,6 +5,85 @@ 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 follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0]
+
+0.4.0 is the first release since 0.2.0. A 0.3.0 version was prepared on
+`main` (version constant and changelog section) but was never tagged or
+published to RubyGems; there is no 0.3.0 release. Everything prepared for it
+ships here, together with the changes made on `main` since.
+
+### Added
+
+- `--as MODEL:ID` on `bin/rails karst:verify` and `bin/rails karst:reproduce` — a human-only way to run a probe as one specific existing record instead of a sampled one (e.g. `karst:verify GET /admin/imports/123 --as User:72`). Resolved exclusively through the same `Identity.resolve` lookup the panel's own **Test as** button already uses, so a record outside a configured principal source never resolves; there is no `constantize`/`find` bypass. Cannot be combined with `--anonymous`, and is not exposed by either MCP tool — an agent can pick a request, never a principal.
+- Runtime-confirmed identity: every probe outcome now carries an `identity` evidence object separating the *requested* identity (intent), the *established* one (setup), and the *observed* one (what the Rails application itself resolved while running the request). `identity.confirmation` fails closed — `confirmed`, `confirmed_anonymous`, `absent`, `mismatch`, `contaminated`, or `unobservable` — and only the first two are evidence about identity.
+- Anonymous probes as a first-class probe kind: `bin/rails karst:verify --anonymous`, and `verify_access(identity: "anonymous")` over MCP. Karst establishes no identity and then verifies the application really did resolve none; stale state that produces a principal anyway is reported as `contaminated`, never as anonymous. An anonymous probe requires no principal source at all.
+- `config.observe_identity`, the observation seam for non-Devise authentication. Devise/Warden applications need no configuration: Karst reads the application's own Warden proxy from the probe request.
+- Halt-time identity observation: when an access callback halts a request, Karst records the identity the application had established *at that decision*, plus `identity.observed_at` and `identity.changed_during_request`.
+- Each outcome now reports the `controller` and `action` the probed request actually dispatched to, and the evidence document carries `provenance` (Karst/Rails/Ruby versions, environment, observation timestamp).
+- **Request reproduction.** Answers "something calls this endpoint -- what
+  request do I send to exercise the same behavior?". Karst issues exactly one
+  caller-specified request through the real application, inside the same
+  rolled-back transaction the access sweep uses, and drives that request's
+  identity through the same requested/established/observed/confirmed
+  lifecycle `verify_access` uses, reporting what it observed: the
+  controller/action that dispatched, the router's own route parameters, the
+  halted callback, the response, database writes -- plus a cURL command for
+  exactly what it sent. Available at `/karst` under **Reproduce request**, as
+  `bin/rails karst:reproduce METHOD PATH`, and as the `reproduce_request` MCP
+  tool. Secrets never come back out: parameters pass through the application's
+  own `config.filter_parameters` (Rails' own `ActiveSupport::ParameterFilter`)
+  plus a conservative credential-name net, and credential-bearing headers
+  become placeholders such as `<API_KEY>` without their values ever being read.
+  See [docs/request-reproduction.md](docs/request-reproduction.md).
+- MCP now exposes two tools. `verify_access` is unchanged and stays GET-only.
+- Reproduction evidence now reports `execution.controller_completed` (did the
+  Rails controller lifecycle finish without raising -- distinct from whether
+  it dispatched at all), `execution.exception_phase` (the most specific phase
+  -- `controller`, `render`, or `unknown` -- that instrumentation actually
+  proves a raised exception occurred in, derived from
+  `ActiveSupport::Notifications` events rather than the exception's class or
+  message), and `execution.rendered` (the templates, partials, and layouts
+  Karst observed being rendered or raising, by structural virtual path only).
+
+### Fixed
+
+- **`bin/rails karst:mcp` reported a missing `mcp` gem when the installed one was merely outside Karst's supported range.** An application whose bundle resolved `mcp` to a version Karst did not admit -- for example 1.6.1, selected through another gem's `mcp ~> 1.5` -- was told to add the dependency it already had. The command now names the version it found and the range it requires, and reports the dependency as missing only when it is.
+- **Request reproduction could echo a secret through Referer, Origin, or a redirect.** `Reproduction::Sanitizer` treated `Referer` and `Origin` as safe, request-shape headers and echoed them verbatim, but both are URLs whose query string (and, for an OAuth-style redirect, fragment) can carry a real credential — `Referer: https://example.test/reset?token=...`, `Referer: .../callback#access_token=...`. They are now parsed as URLs and stripped to scheme/host/path (query, fragment, and userinfo discarded) rather than treated as safe or matched against the credential-name net; a value that does not parse as a URL at all is masked outright. `Access::Probe`'s own redirect sanitization had the same gap in the other direction: it stripped a redirect's query string but not its fragment (`/callback#access_token=...` came back whole), and its own parse-failure fallback split only on `?`, not `#`. Both are now stripped, in both the happy path and the fallback.
+- **A reproduced application's own `filter_parameters` raising silently fell back to the global `Rails.application`'s, not to "no application filters."** `Reproduction::Exercise` already documented that it must never let `Sanitizer` reach for `Rails.application` in place of the application Karst actually issued the request against, but its own error handling returned `nil` on failure, which `Sanitizer` treats as "no filters were given, read the global" — exactly the fallback the documented contract rules out. It now returns an empty Array, so a broken or unavailable `filter_parameters` means this application declared none, never a stranger's rules applied to its parameters.
+- **Outcome groups were split by timing.** The `karst:verify --json` / MCP `verify_access` evidence grouped outcomes by a key that included each probe's own `elapsed_ms`, so equivalent outcomes (25 users all halted at `require_admin` with `403`) came back as up to 25 separate groups. Outcomes are now grouped by what the request observed only — status, redirect, halted callback, exception, dispatched controller/action, writes, and the configured usable verdict — through one shared definition (`Karst::Access::OutcomeGroups`) that the CLI, MCP, and `/karst` panel all use.
+- The human `karst:verify` output described a whole sample using only its *first* probe's status and identity; it now summarizes every outcome.
+- Repeated configuration work during one operation. Setup checks, the search, and every **Test as** button on `/karst` each re-resolved the effective principal sources — re-reading the approval file, re-parsing model source, and re-running the `principals` callable — up to once per listed user on the inferred-Devise path. Each operation now resolves them once (`Karst::Identity::Snapshot`); a later operation still sees changed configuration.
+- A `/karst` request that found no usable outcome and went on to discover candidate populations to suggest still re-read the approval file and re-parsed model source independently of the resolution `Identity::Snapshot` had already just taken (`Web::Middleware#inline_population_candidates`) — now it reuses that same read and parse. Approving a population still resolves configuration twice (once to validate the submission before the write, once more for the fresh render after it), each exactly once, not several times over.
+- **Stale cross-request response evidence in reproduction.** If a request run
+  on the same session immediately before the target (identity establishment,
+  most often) completed, and the target then raised before producing a
+  response of its own, Karst could report the *earlier* request's status,
+  content type, and redirect as if it had observed them for the target --
+  because `ActionDispatch::Integration::Session` only updates its
+  request/response objects after the target's own `app.call` returns without
+  raising. Response evidence (`status`, `response_content_type`, `redirect`)
+  is now read only when Karst can prove it belongs to the target request;
+  otherwise it is `nil` and named in `unobserved`, exactly like any other
+  fact Karst did not observe. See
+  [docs/request-reproduction.md](docs/request-reproduction.md).
+
+### Changed
+
+- Optional MCP support now targets the tested MCP 1.5 and 1.6 series
+  (`gem "mcp", ">= 1.5.0", "< 1.7"`), replacing 0.2.0's stale MCP 0.9.x
+  constraint that conflicted with current integrations and failed schema
+  validation with JSON 3.x. CI exercises both the oldest admitted release
+  (1.5.0) and the newest 1.6.x.
+- **Verification evidence schema is now version 3** (0.2.0 emitted version 1; version 2 existed only on unreleased main).
+  - The ambiguous `principal` / `verified_principal` keys are gone rather than renamed in place: a consumer reading "principal" and believing it described the request that actually ran is exactly the false attribution this schema exists to make impossible. Outcomes carry `identities` (each with `requested`, `observed`, `confirmation`), and the top level carries `verified_identity`.
+  - Grouped `outcomes` (under `sample` and each population) no longer carry `elapsed_ms` — a group of several probes has no single elapsed time; `verified_outcome.elapsed_ms` and `summary.elapsed_ms` are unchanged — and gain `verified_usable`. Groups are ordered largest first.
+- **Reproduction evidence schema is version 3.** Request reproduction is new in this release, so version 3 is the first one published; versions 1 and 2 existed only on unreleased main. Relative to those:
+  - Its `identity` document reports `requested`/`observed`/`confirmation` (a `Karst::Identity::Evidence`) rather than echoing back the identity Karst assumed as if it were what ran; a mismatch, absence, or unobservable outcome now stays visible instead of being reported as "sent as User X."
+  - `execution` gained `controller_completed`, `exception_phase`, and `rendered` (additive), but `response.status`/`response_content_type`/`redirect` also stopped trusting `session.request`/`session.response` once a target request raised before producing one -- see Fixed, above. A consumer that read those fields after `execution.exception_class` was already set was reading a value from an earlier request; it now reads `nil`, named in `unobserved`.
+- A probe whose identity setup fails now still runs and is still observed, and reports the failure as `identity.establishment` rather than as an application exception — "asked for User #123, application saw nobody, halted at `authorize_admin`" is the evidence that matters most there.
+- Per-probe write and halted-callback observation now ignores notifications raised on other threads, so a concurrent request in a development server cannot be counted as a probe's own evidence.
+- `karst:verify` prints a bounded outcome summary: one line per observed outcome with its user count, largest first, a few example users for each outcome other than a single largest one, identity confirmation counts, and write warnings. `--json` still carries every user.
+
 ## [0.2.0]
 
 ### Added
@@ -50,5 +129,6 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 - 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
+[0.4.0]: https://github.com/SilenceDogood1984/karst/releases/tag/v0.4.0
+[0.2.0]: https://rubygems.org/gems/karst/versions/0.2.0
+[0.1.0]: https://rubygems.org/gems/karst/versions/0.1.0

data/CONTRIBUTING.md

@@ -32,7 +32,7 @@ Every behavior change requires tests at the narrowest useful level. Bug fixes sh
 
 ### Rails compatibility
 
-Karst's compatibility harness currently covers Rails 6.1 on Ruby 2.7, Rails 7.0 and 7.1 on Ruby 3.2, and Rails 7.2 and 8.0 on Ruby 3.3. The Rails 6.1 / Ruby 2.7 job is blocking, the same as every other row: Karst claims that floor because CI proves it, not the other way around. See [ARCHITECTURE.md](ARCHITECTURE.md#compatibility-policy) for how optional features (currently: the page-local badge) degrade on that floor instead of raising.
+Karst's compatibility harness currently covers Rails 6.1 on Ruby 2.7, Rails 7.0 and 7.1 on Ruby 3.2, and Rails 7.2, 8.0, and 8.1 on Ruby 3.3. The Rails 6.1 / Ruby 2.7 job is blocking, the same as every other row: Karst claims that floor because CI proves it, not the other way around. See [ARCHITECTURE.md](ARCHITECTURE.md#compatibility-policy) for how optional features (currently: the page-local badge) degrade on that floor instead of raising.
 
 The repository uses version-specific Gemfiles under `gemfiles/`. This keeps each dependency set explicit and lets Bundler and CI use their standard `BUNDLE_GEMFILE` behavior without an additional dependency-management tool. Matrix lockfiles are intentionally not committed: compatibility CI resolves the current dependency set allowed by each Rails line, so it detects dependency-resolution regressions instead of only testing a previously locked snapshot. To run one target locally:
 
@@ -43,3 +43,11 @@ BUNDLE_GEMFILE=gemfiles/rails_7_2.gemfile EXPECTED_RAILS_VERSION=7.2 \
 ```
 
 Run every compatibility target with `bin/test-rails`. To add a Rails version, add a version-specific Gemfile, add it to `bin/test-rails`, and add the matching Rails/Ruby entry to the `rails-integration` matrix in `.github/workflows/ci.yml`. Choose a Ruby version on which that Rails release installs and runs, and keep linting out of the compatibility matrix.
+
+The optional MCP dependency has its own, smaller matrix. `Karst::Mcp::Compatibility::REQUIREMENTS` is the one range both the gemspec and `bin/rails karst:mcp` enforce, and the `mcp-compatibility` CI job runs the MCP specs and the shared-process integration suite against its oldest admitted release (`gemfiles/mcp_1_5_0.gemfile`) and the newest release of its latest admitted series (`gemfiles/mcp_1_6.gemfile`). To admit a new MCP series, test it the same way first, then widen `REQUIREMENTS` and move the newest-series Gemfile and matrix entry to it. To run one MCP target locally:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/mcp_1_6.gemfile bundle install
+BUNDLE_GEMFILE=gemfiles/mcp_1_6.gemfile EXPECTED_RAILS_VERSION=8.0 EXPECTED_MCP_REQUIREMENT="~> 1.6.0" \
+  bundle exec rspec spec/mcp spec/integration --exclude-pattern "spec/integration/*golden_path*"
+```

data/README.md

@@ -47,6 +47,23 @@ 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:
@@ -83,13 +100,85 @@ 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", "~> 0.9.0"
+gem "mcp", ">= 1.5.0", "< 1.7"
 ```
 
 ```bash
@@ -105,7 +194,28 @@ 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
 
@@ -130,9 +240,13 @@ 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
 ```
 
+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.
@@ -143,6 +257,8 @@ Karst is for local development only — `/karst`, the badge, and Test As only wo
 
 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/docs/advanced-configuration.md

@@ -4,6 +4,24 @@ 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.
@@ -23,6 +41,16 @@ 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 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.
@@ -44,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`.
@@ -129,6 +226,14 @@ Deliberately machine-local, git-ignored development state, not project configura
 
 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 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.
+
+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.
+
 
 ## Full configuration reference
 
@@ -148,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

@@ -14,7 +14,7 @@ Karst to read. Guessing from column names (`password_digest`), class names
 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
+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
@@ -99,7 +99,27 @@ 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
+## 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
@@ -125,7 +145,7 @@ 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
+## 6. Stop Testing As
 
 ```ruby
 Karst.configure do |config|
@@ -137,7 +157,7 @@ Karst.configure do |config|
 end
 ```
 
-This is the whole recipe. There is no sixth step, and nothing above reaches
+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