rails-ai-context 5.19.1 → 5.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 175ccbf5bac4703a8f9699708a02435a9b80546c09129deae79ffb5f182e14e6
-  data.tar.gz: 0adbdf439e6ac853606fc786d6f92041a70aec4e2379ebfe98132eb14352b219
+  metadata.gz: 5e92439f72b8f723d75c6b62ca2fe3734f29b60548e50d2ddea836c93a66d952
+  data.tar.gz: c541d140c1f7971fa0f62d5e664673a338ffc7e809b8df8578035890224567d0
 SHA512:
-  metadata.gz: 9bb08e8b5d06124360be6870c7f667f008a666d07bea55a33b89662049ea1ee00b3ab88b5c5060ee70c47b8d1b77c422cfd8434f3327094427e2ac321c8a9201
-  data.tar.gz: 160c8b647c1a6be4bec7290be0308a98318edd92c2525235410bd1fed94459ddd107538f5ced4c8fced29745a9de00aa8dfc37f0bdc9274afa358c0aa2f82e3f
+  metadata.gz: e2e550d201dd7af30d4e95e5ec368d2f376d2b8812d5254ffcf10ab8f78b1f0e089df5ba5f2664fbe858dbf2a5277c15e2489df0e86b61b22ebd44868560854f
+  data.tar.gz: 80daba010490cd5b6d1e0c4e770582b4bda8db4d073ebb9bead8d2eb3f015ec966c1ce1fef60f229755e1f1610b48b2287da480d790f20ed3be705d8b4ee95d7

data/CHANGELOG.md

@@ -5,6 +5,134 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.20.0] - 2026-08-11
+
+### Security
+
+- **Initializer config values are redacted where they are read, not where
+  they are rendered.** The config-assignment listener served raw source
+  slices, so a `config.secret_key = "..."` in `devise.rb` reached
+  `rails_get_context` and the generated context files in plaintext. Values
+  assigned to secret-named settings are now filtered at emission, which
+  covers every current and future reader of that listener.
+- **Redaction and shortening are one operation.** They were separate calls
+  in the caller's hands, and getting the order wrong let a long credential
+  be cut apart before the pattern that would have caught it ever ran. The
+  module exposes `redact_and_shorten`, so the order is not a caller's to get
+  wrong.
+- **The secret vocabulary widens, and nesting no longer hides a value.**
+  `pepper`, `salt`, `master_key`, `signing_key`, `encryption_key`,
+  `deterministic_key` and `encryption.primary_key` now read as secret names,
+  and a value under a secret-named setting is filtered however deeply it
+  nests. `config.secret = { primary: [ "..." ] }` emitted the credential in
+  full.
+
+### Changed
+
+- **The prism floor rises from 0.28 to 1.4.** The old range was a claim
+  nothing tested. A CI leg now pins prism at exactly 1.4.0 on Ruby 3.2, where
+  prism is a real gem rather than stdlib, with a trimmed gemfile so a dev
+  dependency cannot resolve it upward and turn the floor into a test of
+  whatever version won. A scheduled allowed-to-fail leg runs the suite
+  against prism's main branch, so a removal there surfaces here rather than
+  in your bundle. 0.28 was measured green in the one configuration that could
+  be checked locally; the raise is a tightening to a version CI proves, not a
+  fix for a known break.
+- **Redaction markers converge on `[FILTERED]`.** One module now owns the
+  patterns and the vocabulary. `[EMAIL]` stays as the one semantic marker.
+  Marker presence and this vocabulary are contract going forward; see the
+  output contract in `docs/SECURITY.md`.
+
+  | Was | Now |
+  |-----|-----|
+  | `[REDACTED]` | `[FILTERED]` |
+  | `[redacted]` | `[FILTERED]` |
+  | `[ENV VAR REDACTED]` | `[FILTERED]` |
+  | `[dotenv] Set [ENV VARS REDACTED]` | `[dotenv] Set [FILTERED]` |
+  | `[EMAIL]` | `[EMAIL]` (unchanged) |
+
+- **`rails_get_schema` says "failed:" where it used to say "not available:"**
+  when the introspector raised. It was the only one of the sixteen tools
+  carrying that preamble whose failed-case wording differed; it now shares
+  the phrasing the other fifteen use. The not-available and unavailable
+  answers are unchanged.
+- **An invalid `detail` answers at the default level and says it did.**
+  Eleven tools each answered `Unknown detail level: x` and nothing else;
+  `detail` is normalized once now, before any tool runs, so junk and omission
+  both land on the default. You still get told: the response carries a note
+  naming the value that was discarded and the levels that exist, so a typo is
+  visible without eleven copies of the check. Tools that spell their own
+  levels (`rails_onboard`: quick/standard/full) are untouched.
+- **Listener registration is derived from the listener.** Defining an `on_*`
+  handler is now its registration, validated against the events the running
+  prism dispatches, so a typo'd handler raises instead of never firing. The
+  hand-typed event allowlist that shipped the 5.19.1 fabricated-routes bug is
+  gone, along with the hydrator's private copy of it.
+- **MCP view resources resolve through the current app root** rather than
+  `Rails.root`, so `rails-ai-context://views/...` works in the static tier.
+- **One error frame for the MCP edge.** The middleware and the engine
+  controller each built their own JSON-RPC internal-error body; both now read
+  it from one place, so a failure looks the same whichever transport served
+  it. Transport construction moves behind one factory; memoization stays with
+  each caller, which holds a different scope (per instance, per class, per
+  process).
+- **A setting's name decides whether it is redacted, not its value's type.**
+  `config.secret_key = 12345` was filtered in one emitted field and left plain
+  in the other, because one path saw an Integer and the other saw the source
+  text. One decision drives both now.
+
+### Added
+
+- **Twenty-seven sections now answer with the app not booted.** Gems, i18n,
+  views, view templates, tests, jobs, turbo, stimulus, assets, devops, seeds,
+  middleware, engines, components, performance, credentials, env and the rest
+  read files the static tier already had on disk; they refused only because
+  nothing had said they could answer. Each introspector now declares its
+  static tier (files-only, alternate-source, or runtime-only), an undeclared
+  one fails the suite, and every files-only declaration is proven against a
+  fixture app with nothing booted. Runtime-only sections - config, api,
+  conventions, autoload, security, observability, database stats, connection
+  pool, initializers - still refuse honestly.
+
+### Fixed
+
+- **Re-running install through a different entry keeps your AI-tool
+  selection.** The Rails generator read it from the initializer, the
+  standalone CLI read it from `.rails-ai-context.yml`, and the rake task
+  kept a third copy of the logic. Switching between them silently dropped
+  the previous choice and re-prompted from scratch. All three read and write
+  the same record now, initializer first on read because that is the file you
+  hand-edit. Recording the selection also reaches both files together, so an
+  entry can no longer leave a stale initializer that outranks the YAML it
+  just wrote. An initializer with a `configure` block but no selection line
+  now gets one from any entry, not just the rake task.
+- **The standalone HTTP server scopes its session record per client.** The
+  Rack middleware and the engine controller got this; `rails-ai-context serve
+  --transport http` serves many clients from one process too and was still
+  pooling their `rails_session_context` history.
+- **The generated guide advertised a CLI command that does not exist.** Its
+  row for `rails_get_env_config` printed `ai:tool[environments]`, which the
+  CLI cannot resolve; the CLI name is now derived from the tool name rather
+  than typed beside it.
+- **One MCP client's session record no longer shows up in another's.**
+  `rails_session_context` kept one process-global list of calls, which is
+  right over stdio but wrong for the two HTTP transports, where a single
+  process serves every client. The record is now bucketed by
+  `Mcp-Session-Id`. A caller's snapshot of the record also stopped changing
+  under it: `session_queries` returned live entries that later calls kept
+  mutating.
+- **`.env.example` placeholders are shown, not filtered.** A
+  `<your-secret-here>` came back as `[FILTERED]`, hiding the one thing an
+  example file exists to show. A credential's shape and a placeholder's are
+  told apart now.
+- **The HTTP session record evicts the least recently used client, and is
+  bounded.** It dropped the oldest-created session, which is usually the
+  busiest one still in use, and it grew for as long as the process lived.
+- **Tools no longer report themselves as failing on mcp 0.8.** The note
+  naming a discarded `detail` value read `meta` off the response, which the
+  0.8 SDK has no reader for, so building the note raised and the tool
+  answered `Tool ... failed:`.
+
 ## [5.19.1] - 2026-08-10
 
 ### Fixed

data/CONTEXT.md

@@ -12,6 +12,22 @@ Overloaded. Always qualify it; never use "environment" bare in a tool name, an i
 
 **Environment** (unqualified, as data) - a single named Rails environment: development, production, staging. This is the only sense in which the bare word is allowed, and only as a value, never as a name. The `:environments` payload key means "the list of these", which is why it kept its name when the introspector was renamed.
 
+## AI tool
+
+The assistant a user points at their app: claude, cursor, copilot, opencode, codex. What the gem generates for one is its **context files** (`CLAUDE.md`, `.cursor/rules/*.mdc`, and so on).
+
+Avoid "format" for either sense - claude is not a file format, and the word collides with real formatting elsewhere in the code. The public config key `ai_tools` already uses the canonical term.
+
+`Install::AiTool` is the one table of what each means: name, context files, MCP config shape, legacy leftovers. `Install::SelectionRecord` owns which ones the user picked - written to YAML always and to the initializer line inside a Rails app, read initializer-first because that is the file a user hand-edits.
+
 ## Static tier
 
-The mode where the app did not boot, or `--no-boot` was passed. An introspector answers in this tier only if it defines `static_call`. Two shapes count as defining it: reading a different source (parsing `db/schema.rb` instead of querying the connection), and reading the same source a booted app would (a file-based introspector, where `static_call` is the same work under another name).
+The mode where the app did not boot, or `--no-boot` was passed. What an introspector answers here is what it declared, never what a runtime check happened to detect. Every introspector in `INTROSPECTOR_MAP` extends `StaticTier` and names one of three kinds:
+
+**files-only** - `call` runs unchanged against the static app handle, because it only ever read files. Most of the map.
+
+**alternate-source** - `static_call` answers from a different source than `call` does: `db/schema.rb` instead of the connection, `config/routes.rb` instead of the route set.
+
+**runtime-only** - needs `app.config`, `app.routes` or a live database, and refuses honestly.
+
+An undeclared introspector fails the suite, and every files-only declaration is proven against `spec/fixtures/static_app` with nothing booted. Declaring files-only while defining `static_call` (or the reverse) is also a spec failure.

data/CONTRIBUTING.md

@@ -33,16 +33,18 @@ lib/rails_ai_context/
 1. Create `lib/rails_ai_context/introspectors/your_introspector.rb` (auto-loaded by Zeitwerk)
 2. Implement `#initialize(app)` and `#call` → returns a Hash (never raises)
 3. Register it in `lib/rails_ai_context/introspector.rb` (the `INTROSPECTOR_MAP`)
-4. Add the key to the appropriate preset(s) in `Configuration::PRESETS` (`:full` is the default, `:standard` for core-only)
-5. Write specs in `spec/lib/rails_ai_context/your_introspector_spec.rb`
+4. `extend StaticTier` and declare one: `static_tier :files_only` if `#call` runs unchanged with nothing booted, `:runtime_only` if it needs live reflection, or `:alternate_source` plus a `static_call` reading elsewhere. A mapped introspector that declares nothing fails the suite
+5. Add the key to the appropriate preset(s) in `Configuration::PRESETS` (`:full` is the default, `:standard` for core-only)
+6. Write specs in `spec/lib/rails_ai_context/your_introspector_spec.rb`
 
 ## Adding a New MCP Tool
 
 1. Create `lib/rails_ai_context/tools/your_tool.rb` inheriting from `BaseTool` (auto-loaded by Zeitwerk)
 2. Define `tool_name`, `description`, `input_schema`, and `annotations`
 3. Implement `def self.call(...)` returning `text_response(string)`
-4. Auto-registered - no manual list to update (BaseTool.inherited tracks it)
-5. Write specs in `spec/lib/rails_ai_context/tools/your_tool_spec.rb`
+4. Declare `guide_row(order:, mcp:, cli_args:, summary:)` - the generated guide is derived from it. A tool without one fails the inventory spec, and `order` must be unique and leave no gap in the sequence
+5. Auto-registered - no manual list to update (BaseTool.inherited tracks it)
+6. Write specs in `spec/lib/rails_ai_context/tools/your_tool_spec.rb`
 
 ## Adding a Prism Listener
 
@@ -52,7 +54,7 @@ Listeners extract specific concerns (associations, validations, etc.) from the A
 2. Implement `on_call_node_enter(node)` and/or `on_def_node_enter(node)` - only the events your concern needs
 3. Use `confidence_for(node)` from `BaseListener` to tag results `[VERIFIED]` or `[INFERRED]`
 4. Store results in `@results` (accessed via `#results`) as plain hashes, never Prism nodes
-5. If your listener needs an event `SourceIntrospector.register_listener` doesn't already wire up, add it there
+5. Nothing to register - `ListenerRegistration` derives the events from the `on_*` methods you defined, and raises if one names an event prism never dispatches
 6. Register the key/class pair in `SourceIntrospector::LISTENER_MAP` only if the listener should run on every model walk; listeners used by one introspector are passed to `SourceIntrospector.walk(path, key => Listener)` at the call site instead
 7. Write specs in `spec/lib/rails_ai_context/introspectors/listeners/your_listener_spec.rb`
 8. Add a row to the listener catalogue in `docs/INTROSPECTORS.md`

data/app/controllers/rails_ai_context/mcp_controller.rb

@@ -27,6 +27,32 @@ module RailsAiContext
     end
 
     def handle
+      Tools::BaseTool.with_session_for(request.env) do
+        serve_transport
+      end
+    rescue => e
+      # Once the response is committed the status and headers are already on
+      # the wire, so a JSON-RPC frame written here cannot reach the client.
+      # Worse, assigning a body swaps the stream out from under the thread
+      # still draining the old one, turning a truncated SSE stream into a
+      # garbled one. The streaming branch's ensure always closes the stream,
+      # and closing commits, so every streaming failure lands here committed.
+      # Hand those to Live, which logs them with a backtrace and tears the
+      # connection down.
+      raise if response.committed?
+
+      # A transport failure must still answer in JSON-RPC shape. Without this
+      # the exception escapes into a generic Rails 500 (HTML), breaking the
+      # client's JSON-RPC loop.
+      RailsAiContext.log_warn "[rails-ai-context] MCP request failed: #{e.class}: #{e.message}"
+      self.status = 500
+      response.headers["Content-Type"] = "application/json"
+      self.response_body = McpEdge.internal_error_frame(e)
+    end
+
+    private
+
+    def serve_transport
       status_code, rack_headers, body = self.class.mcp_transport.handle_request(request)
       self.status = status_code
       apply_transport_headers(rack_headers)
@@ -67,32 +93,8 @@ module RailsAiContext
       else
         self.response_body = body
       end
-    rescue => e
-      # Once the response is committed the status and headers are already on
-      # the wire, so a JSON-RPC frame written here cannot reach the client.
-      # Worse, assigning a body swaps the stream out from under the thread
-      # still draining the old one, turning a truncated SSE stream into a
-      # garbled one. The streaming branch's ensure always closes the stream,
-      # and closing commits, so every streaming failure lands here committed.
-      # Hand those to Live, which logs them with a backtrace and tears the
-      # connection down.
-      raise if response.committed?
-
-      # Mirror Middleware#json_rpc_error_response: a transport failure must
-      # still answer in JSON-RPC shape. Without this the exception escapes
-      # into a generic Rails 500 (HTML), breaking the client's JSON-RPC loop.
-      RailsAiContext.log_warn "[rails-ai-context] MCP request failed: #{e.class}: #{e.message}"
-      self.status = 500
-      response.headers["Content-Type"] = "application/json"
-      self.response_body = {
-        jsonrpc: "2.0",
-        error: { code: -32603, message: "Internal error: #{e.message}" },
-        id: nil
-      }.to_json
     end
 
-    private
-
     # Rack 3 transports name their headers in lowercase, and the MCP SDK
     # switched to that in 1.0. Rails 7.0 keeps response headers in a
     # case-sensitive Hash, so a lowercase "content-type" is invisible to the
@@ -131,12 +133,7 @@ module RailsAiContext
       # Class-level memoization - transport persists across requests.
       # Thread-safe: MCP::Server and transport are stateless for reads.
       def mcp_transport
-        @transport_mutex.synchronize do
-          @mcp_transport ||= begin
-            server = RailsAiContext::Server.new(Rails.application, transport: :http).build
-            MCP::Server::Transports::StreamableHTTPTransport.new(server)
-          end
-        end
+        @transport_mutex.synchronize { @mcp_transport ||= McpEdge.build_transport }
       end
 
       def reset_transport!

data/docs/COMPATIBILITY.md

@@ -19,7 +19,7 @@ document is aspirational.
 - **Rails (railties):** 7.0 - 8.1 (gemspec: `railties >= 7.0, < 9.0`)
 - **mcp gem:** `>= 0.8, < 2.0`
 - **thor:** `>= 1.0, < 3.0`
-- **prism:** `>= 0.28, < 2.0`
+- **prism:** `>= 1.4, < 2.0` (a CI leg pins the floor exactly and runs the suite against it)
 - **concurrent-ruby:** `>= 1.2, < 3.0`
 
 The gemspec's `railties` bound is wider than the CI matrix: point releases inside

data/docs/INTROSPECTORS.md

@@ -214,7 +214,7 @@ Passed to `SourceIntrospector.walk(path, key => Listener)` when a specific file
 
 1. Subclass `BaseListener` in `lib/rails_ai_context/introspectors/listeners/`. Use its helpers rather than re-reading nodes: `extract_symbol_args`, `extract_keyword_options`, `extract_arg_values` (source-slice fallback for expressions like `2.hours`), `extract_keyword_sources`, `extract_keyword_nodes`, `keyword_hash`, `constant_path_string`.
 2. Implement the `on_*_node_enter` hooks you need and push plain hashes onto `@results`. Never return Prism nodes as the result itself; `option_nodes` is the one deliberate exception, for callers that must inspect an expression's shape.
-3. Register the event in `SourceIntrospector.register_listener` if it is not already in the list (call, def, class, module, block, singleton class, case, constant write).
+3. Nothing to register. `ListenerRegistration` reads the events off the `on_*` methods you defined, inherited ones included, and raises if one names an event prism never dispatches.
 4. Add a spec of the same name under `spec/lib/rails_ai_context/introspectors/listeners/`.
 5. Add a row to the table above.
 

data/docs/SECURITY.md

@@ -190,14 +190,45 @@ Complex patterns that would cause catastrophic backtracking raise `RegexpError`
 
 ---
 
-## Log redaction
+## Redaction
 
-The `rails_read_logs` tool redacts sensitive data from log output:
+Everything that leaves your app through this gem - log lines, query rows, environment values, config source slices - passes through one redaction module before anything else can touch it. Redacting and shortening are a single operation there, so a long credential cannot be cut apart in a way that hides it from the pattern that would have caught it.
 
-- Passwords and tokens
-- Email addresses
-- Secret values
-- API keys
+What gets redacted:
+
+- Passwords, tokens, secrets and API keys, wherever they are named
+- Credentials embedded in URIs (`redis://user:pass@host`)
+- Email addresses in log lines
+- Values assigned to secret-named settings in initializers
+
+### Markers
+
+Redacted values carry one of two markers, and only these two:
+
+| Marker | Means |
+|--------|-------|
+| `[FILTERED]` | A value was removed because it is or may be a secret |
+| `[EMAIL]` | An email address was removed |
+
+Marker presence and this vocabulary are part of the output contract (see below) - you can pattern-match on them.
+
+---
+
+## Output contract
+
+**Contract, safe to depend on:**
+
+- Tool names and their input schemas
+- The presence of a redaction marker wherever a value was removed
+- The `[FILTERED]` / `[EMAIL]` marker vocabulary
+
+**Incidental, expected to change between releases:**
+
+- Response text, headings and formatting
+- Refusal and unavailability wording
+- Row and section ordering
+
+Pin your assertions to the first list. When something in the second list changes in a way that could break a pinned assertion, the CHANGELOG says so.
 
 ---
 

data/docs/SETUP.md

@@ -298,7 +298,7 @@ Type in Claude Code's prompt:
 What MCP tools do you have access to?
 ```
 
-You should see `rails_get_schema`, `rails_search_code`, and the other 43 tools listed.
+You should see `rails_get_schema`, `rails_search_code`, and the rest of the tools listed.
 
 ### Cursor
 

data/docs/TROUBLESHOOTING.md

@@ -188,7 +188,7 @@ Common false positives:
 - Hash characters in strings → write the hash outside a comment position
 - JSONB operators (`#>>`) → preserved correctly since v5.6.0
 
-### "Column values show [REDACTED]"
+### "Column values show [FILTERED]"
 
 Columns matching sensitive patterns are redacted. Configure:
 

data/docs/adr/0001-own-listener-registration.md

@@ -0,0 +1,9 @@
+# Derive Prism listener registration ourselves, not via prism's register_public_methods
+
+Status: accepted
+
+Prism 1.9+ ships `Dispatcher#register_public_methods`, which looks like the obvious replacement for the hand-typed event allowlist that shipped the fabricated-static-routes bug (c8caa40). We derive registration in our own module instead, for two reasons that are easy to rediscover the hard way: the gem's prism floor is below 1.9, where the helper does not exist, and the helper is built on `public_methods(false)`, which skips inherited handlers - `VariantCallListener` inherits its only handler from `ChainedCallListener` and would register zero events, silently.
+
+(The floor was 0.28 when this was written and is 1.4 now; the first reason holds either way. See the gemspec for the current range, and the `prism floor` CI leg that tests it.)
+
+Our module enumerates `on_*` handlers inheritance-aware and validates every name against the running prism's real event set, raising on unknowns, so an unregistered or typo'd handler fails loud instead of never firing. Do not swap the prism helper back in as a simplification; it reintroduces both silent failure modes.

data/docs/adr/0002-static-tier-declared-not-detected.md

@@ -0,0 +1,5 @@
+# Static tier capability is declared per introspector, never auto-detected
+
+Status: accepted
+
+Every mapped introspector must declare how it answers in the static tier: its `call` already works from files alone, or it refuses honestly, or it defines `static_call` against an alternate static source. We rejected auto-detecting "file-only" introspectors because a default-open guess re-creates the failure mode the tier exists to prevent: an introspector that grows a runtime dependency while still looking file-only would silently serve wrong data (the c8caa40 class). Declaration fails closed - a mapped introspector that declares nothing is a spec failure, and a shared fixture spec proves every files-only declaration true under `StaticApp`.

data/docs/adr/0003-shared-tool-cache-semantics.md

@@ -0,0 +1,23 @@
+# The two shared tool caches: what is a defect and what is intended
+
+Status: accepted
+
+`Tools::BaseTool` keeps two process-global structures - `SHARED_CACHE` (one introspection result for every tool) and `SESSION_CONTEXT` (what has been called with what). Both are read by four entry points - stdio, the Rack middleware, the engine controller and the standalone HTTP server - three of which serve many clients from one process. This records what the audit found, so the next reader does not re-derive it from the mutex.
+
+## Defects, fixed
+
+**One client's session record was served to another.** `SESSION_CONTEXT[:queries]` was a single flat hash. Over stdio that is right - one process is one conversation - but the middleware, the engine controller and the standalone HTTP server each serve every client from one process, so `rails_session_context` listed calls the asking client never made. The record is now bucketed per conversation: all three HTTP entry points wrap each request in `BaseTool.with_session(<Mcp-Session-Id>)`, and stdio falls through to a single default bucket, unchanged.
+
+**`session_queries` handed out live entries.** It returned `values.dup`, a shallow copy, so the entry hashes stayed live inside the record and kept being mutated by later calls - a caller's snapshot changed under it. It now copies each entry.
+
+**The record grew without bound, keyed by a client-controlled header.** Bucketing per conversation introduced a hash whose keys come from `Mcp-Session-Id`, in a process that stays up. Three things were wrong at once: the hash had a default block, so merely *reading* a session's history created a bucket; nothing capped the id's length; and nothing evicted. Reading no longer writes, ids are truncated to `MAX_SESSION_ID_LENGTH`, and the number of remembered conversations is capped at `MAX_SESSIONS`.
+
+Eviction is least-recently-used, not oldest-created. Recording re-inserts the session so hash order tracks use. Ordering by creation instead would evict the conversation that has run for hours ahead of a hundred idle newcomers - backwards, and worst on exactly the long-lived transports that made bucketing necessary.
+
+## Intended semantics, not defects
+
+**The fingerprint walk happens under the mutex, not outside it.** The whole read path in `cached_context` - TTL check, fingerprint comparison, re-introspection - is inside one `synchronize`, so concurrent callers serialize instead of racing to introspect. Twenty threads arriving together produce exactly one introspection. The cost is that a fingerprint walk (~12ms in dev-mode installs, ~0.5ms in production) blocks other tool calls for its duration. That is the trade we want: a lock-free fast path would let several threads run the full 40-introspector walk at once, which is far more expensive than the wait it avoids.
+
+**`deep_dup` also happens under the mutex.** Every caller gets an independent copy, so a tool that mutates its context cannot corrupt the next tool's view. Copying inside the lock adds to hold time, and moving it outside would hand out the cached object itself between the read and the copy. Isolation is worth more than the contention; the copy is cheap next to the introspection it protects.
+
+Both are pinned by `spec/lib/rails_ai_context/tools/shared_cache_concurrency_spec.rb`, which also drives the middleware and the engine controller concurrently against both caches.

data/docs/adr/0004-install-e2e-stays-example-rich.md

@@ -0,0 +1,28 @@
+# The install e2e specs keep their examples; the fast specs took the load instead
+
+Status: accepted
+
+The install program (#116, #117) planned to shrink e2e install coverage to "one smoke per entry", on the stated grounds that install changes were paying a 30-minute loop. Measured before acting, that premise does not hold, so the trim was not made.
+
+## What it costs now
+
+The whole e2e suite is about 4 minutes for 159 examples, and builds 11 throwaway Rails apps. The three install specs account for 3 of those apps and 31 examples in roughly 73 seconds.
+
+Within one install spec, the app is the cost and the examples are nearly free:
+
+| Run | Time |
+|-----|------|
+| `standalone_install_spec.rb`, all 7 examples | 9.6s |
+| the same file, 1 example | 6.5s |
+
+So `rails new` plus `bundle install` is ~6.2s and each further example is ~0.5s. Cutting all three files to one example each would drop ~28 examples and save ~14 seconds of a 4-minute suite. The apps - the actual cost - would all still be built, because the three install paths (in-Gemfile, standalone, zero-config) are what the separate apps exist to distinguish.
+
+## What it would cost to trim
+
+Three of the surviving install examples have no unit-level equivalent, because they exercise the generator's prompting rather than its output: stdin hitting EOF mid-prompt, `--defaults` skipping every prompt, and a re-run being idempotent. Those are the paths that broke before, and they cannot be reproduced without running the real generator against a real app.
+
+## The part of the goal that was real
+
+The intent behind the bullet - that install changes stop paying a slow loop - is served by moving the questions that used to need an app into fast specs. `Install::SelectionRecord` and `Install::AiTool` are unit-tested with no Rails boot, and the entry round-trip that used to justify three e2e runs is now `spec/lib/rails_ai_context/install/entry_parity_spec.rb`, which runs in milliseconds.
+
+Revisit this if the app-build count grows or if a fixture app can be built once and shared across install paths. Deleting examples is not the lever.