ractor-rails-shim 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2f462e8a604fac024cc13b3f1667ec9e9c79207cb675a473e7f2f536e7ac4c8d
+  data.tar.gz: 76652b85a06f3c7e6cc50b7619f4b28c52da420f6f946f09518f01b5143c4094
+SHA512:
+  metadata.gz: 83964fbfa3a113e70ca8bdfd5f6f69ea3598cf028207bb43971a9b6ed135e28f4b2f2a5b1d0bbcdf574a9a12313ff9ab6664182d22b8a3e00ab959105bdb72ce
+  data.tar.gz: be2ef63949ea84ac7f3dfa72a65d57f2687b2b1dc53de6f85a8709d42b84fcec5588f429e298beb8aa76e682b593ebfeb49dd292191cc620bd847b9b84e78c78

data/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+All notable changes to ractor-rails-shim are documented here.
+
+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).
+
+## [Unreleased]
+
+### Added — ActiveRecord query-path ractor-safety (Blocker 1 deep work)
+- `RactorRailsShim.worker_ar_init(app)` — a shareable Rack middleware that
+  calls `init_worker_ar_connections!` on each worker's first request. Kino's
+  `:ractor` mode has no worker-init hook, so `config_ractor.ru` (generated by
+  `make_full_test_app.sh`) now wraps the shareable app with it.
+- `_share_relation_delegate_caches!` — deep-freezes each AR model class's
+  `@relation_delegate_cache` (mutable Hash of shareable delegate Classes) so a
+  worker Ractor can read it. (`patches/activerecord.rb`)
+- `_share_model_classes!` — warms every AR model class in main (runs
+  `count`/`first`/`page`/`table_name`/...) to populate lazy `@ivar ||= ...`
+  class ivars, then makes each shareable (deep-freeze; Monitor/Mutex→
+  `NoOpLock`; `Concurrent::Map`→frozen Hash; unfreezable caches→frozen empty
+  container). Fixes `@table_name`, `@arel_table`, `@predicate_builder`, etc.
+- `_share_active_record_internals!` — warms `.empty` + freezes class ivars on
+  the AR `*Clause` helper classes (`WhereClause`, `FromClause`).
+- `_install_activerecord_configurations_patch` — routes the raw
+  `@@configurations` class var (`ActiveRecord::Base.configurations`) through
+  IES with a shareable deep-frozen `DatabaseConfigurations` fallback.
+- ~30 non-shareable AR/Arel constants registered in `SHAREABLE_CONSTANTS`
+  (`VALID_UNSCOPING_VALUES`, `MULTI_VALUE_METHODS`, `STRING_OR_SYMBOL_CLASS`,
+  `NATIVE_DATABASE_TYPES`, ...). `make_constant_shareable` now special-cases
+  Monitor/Mutex constants → `NoOpLock` and rescues intrinsically-unshareable
+  values (Proc / `Concurrent::Map` / `TypeMap`) instead of crashing.
+- `_capture_ar_configurations!` now reads
+  `Rails.application.config.database_configuration` (`DatabaseConfigurations`
+  has no `#each` in this Rails/Ruby).
+- `verify_blockers.rb` (generated by `make_full_test_app.sh`) — end-to-end
+  data-layer + HTTP-dispatch check in a worker Ractor.
+
+### Known limitations (DB queries from worker Ractors)
+- `Post.count` / `Post.page(1)` from a worker Ractor still fail at
+  `ActiveRecord::DatabaseConfigurations.db_config_handlers` (an Array of
+  **Procs** registered by adapters), and downstream at the SQLite
+  `TYPE_MAP` (Procs) and `QUOTED_*` `Concurrent::Map` quoting caches.
+  These are intrinsically unshareable and require upstream Rails changes
+  (shareable callables instead of Procs; per-Ractor quoting caches). See
+  `NEXT_STEPS.md` "The wall — deep AR ractor-unsafety".
+
+## [0.2.0] - 2026-07-09
+
+### Added — productionization (Phase 6)
+- **Version detection infrastructure.** New `RactorRailsShim::Version` module
+  with `Gem::Version`-based runtime checks (`ruby`, `rails`, `rails_segment`,
+  `supported_ruby?`, `supported_rails?`, `satisfies?`). Replaces the string-
+  prefix compare so pre-release and patch versions sort correctly.
+  (`lib/ractor_rails_shim/version_check.rb`)
+- **Version policy switch.** `RactorRailsShim.version_policy = :warn | :strict |
+  :off`. The default `:warn` preserves backward compatibility; `:strict`
+  raises `RactorRailsShim::UnsupportedVersionError` on untested Rails/Ruby;
+  `:off` silences. (`patches.rb`)
+- **Patch version registry.** Every `install_*` / `_install_*` method registers
+  its tested Rails versions in `RactorRailsShim::PATCH_VERSIONS`. Use
+  `RactorRailsShim.applicable_patches` to see which patches applied to the
+  runtime (and which were skipped as untested). This is the "load different
+  patches for different Rails versions" extension point — to add 7.x support,
+  write version-specific variants and tag them in the registry.
+  (`patches.rb`)
+- **CI.** GitHub Actions workflow (`.github/workflows/ci.yml`): a fast unit
+  job (no Rails) plus an integration job that builds the minimal Rails 8.1
+  test app, makes it shareable, and dispatches `GET /up` in a worker Ractor —
+  asserting HTTP 200. Also runs `ractor-rails-check` against the test app.
+- **Unit specs** for the version infrastructure and the callable/lock
+  replacement classes (`NoOpProc`, `Callable`, `CallableConst`,
+  `RequestCallable`, `NoOpLock`, `NoOpLogDev`) — including cross-Ractor
+  callability. (`spec/version_spec.rb`; 31 specs total, up from 8.)
+- **CHANGELOG.md.**
+
+### Changed
+- `ractor-rails-shim.gemspec`: real metadata (`changelog_uri`,
+  `bug_tracker_uri`, `rubygems_mfa_required`), canonical repo URL, CHANGELOG
+  included in the gem package.
+- `script/make_test_app.sh`: portable `sed` (was macOS-only `sed -i ''`,
+  failed on Linux CI).
+- Bumped version `0.1.0` → `0.2.0`.
+
+### Fixed
+- `.gitignore`: corrected `racker-rails-shim-*.gem` typo to
+  `ractor-rails-shim-*.gem`.
+
+## [0.1.0] - 2026-07-09
+
+### Added
+- Initial proof-of-concept. Reroutes Rails class-level instance variables
+  (`Rails.application`, `Rails.cache`, `Rails.logger`, `mattr_accessor`,
+  `class_attribute`, `Zeitwerk::Registry`, unshareable constants) through
+  `IsolatedExecutionState` / `Ractor.make_shareable`.
+- `make_app_shareable!` — replaces self-capturing Procs with callable objects,
+  Mutex/Monitor with no-op locks, `Concurrent::Map` with frozen Hashes, then
+  `Ractor.make_shareable(app)`. A worker Ractor dispatches `GET /up` → 200.
+- `ractor-rails-check` CLI audit tool.
+- Minimal unit specs (8) + an integration spec (self-skips without a test app).
+- `VALIDATION.md`, `README.md`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,265 @@
+# ractor-rails-shim
+
+A monkey-patch shim that reroutes Rails' class-level instance variable accessors through `ActiveSupport::IsolatedExecutionState`, which is Ractor-safe. Lets a Rails app run in Ractor mode without forking Rails itself.
+
+**Status:** proof-of-concept / stopgap. The goal is for Rails to do this upstream, at which point this gem becomes a no-op and can be removed.
+
+**Current status:** on a full Rails 8.1 app (Devise 5, Propshaft, Kaminari,
+PG) under Ruby 4.0.5, worker Ractors serve **every** routable action —
+`GET /up`, full ERB view rendering, Devise sign-in/sign-out (CSRF issuance
+**and** validation), and authenticated Devise **writes** (`POST /posts` → 302,
+row persisted). A worker Ractor dispatches `GET /up` → **HTTP 200** via
+`RactorRailsShim.make_app_shareable!`. The shim builds a shareable fallback
+table for framework class config (`class_attribute` / `mattr_accessor` values)
+and patches the raw class-ivar accessors Rails reads per-request
+(`ExecutionWrapper.active_key`, `Notifications.notifier`, `Inflections`,
+`PathRegistry`, `I18n`, `AbstractController` lazy ivars, `Rack::Request`/`Utils`,
+`ExecutionContext`, etc.).
+
+**Known limitation:** sustained *concurrent* writes in a worker Ractor can still
+crash with a frozen-iseq SIGBUS (a Ruby 4.0 Ractor-model issue); reads and
+single writes are stable.
+
+## Requirements
+
+- **Ruby >= 4.0** — the shim relies on Ruby 4.0's Ractor semantics and
+  `Ractor.make_shareable`. It will not work (and refuses to install) on
+  earlier Ruby versions.
+- **Rails ~> 8.1** — tested against Rails 8.1.x class layouts. Other versions
+  are not yet supported (see Version compatibility below).
+
+**Ractor-mode server:** as of this writing, the only Ruby web server that can
+run a Rails app in Ractor mode is
+[kino](https://github.com/yaroslav/kino) (`kino -m ractor`). Other servers
+(Puma, Falcon, …) run Rails in processes or threads, not Ractors. This shim was
+developed and tested against a real Rails 8.1 app **served by kino**; that is
+the configuration it is verified against.
+
+## Why
+
+Rails stores global state in class-level instance variables:
+
+```ruby
+class Rails
+  class << self
+    attr_accessor :app_class, :cache, :logger
+    def application; @application ||= ...; end
+  end
+end
+```
+
+From a non-main Ractor, these reads/writes raise `Ractor::IsolationError`:
+
+```
+can not get unshareable values from instance variables of classes/modules
+from non-main Ractors
+```
+
+This is the primary blocker preventing Rails from running in Ractor mode (see the [kino](https://github.com/yaroslav/kino) project's `doc/rails-on-ractors.md` for the full diagnosis). The same pattern blocks Hanami, Padrino, Sinatra, and most Ruby web frameworks.
+
+## How it works
+
+The shim reroutes the accessor methods through `ActiveSupport::IsolatedExecutionState`, which is thread-local storage (`Thread.current[:key]`). Each Ractor has its own threads, so each Ractor gets its own slot automatically — verified on Ruby 4.0.5. Rails already uses this primitive for `ActiveRecord::ConnectionHandling.connection_handler` (for thread safety), so the pattern is proven in production.
+
+Two storage paths, depending on the state's shape:
+
+| path | primitive | sharing | mutability | use case |
+|---|---|---|---|---|
+| **per-Ractor** | `IsolatedExecutionState` / `Ractor.store_if_absent` | none (each Ractor own copy) | mutable | connection pools, per-Ractor config, logger |
+| **shareable** | `Ractor.make_shareable` + constant | one copy, by reference | frozen (read-only) | route tables, frozen config, templates |
+
+The shim uses the per-Ractor path by default. For shareable state, use `Ractor.make_shareable` directly — that's not this gem's job.
+
+**Load order.** `install` may be called either before or after Rails is defined — the normal `config/boot.rb` path calls it before `require "rails"`. The `mattr_accessor` macro patch applies regardless; the Rails-module accessor patch (`Rails.application`, `Rails.env`, ...) defers via a `TracePoint(:class)` load hook that fires when `module Rails` opens.
+
+## Version compatibility
+
+The shim targets specific Rails class layouts (8.1.x) and Ruby Ractor semantics
+(4.0.x). At install it runs a real `Gem::Version`-based check (not a string
+compare) and applies a configurable policy on mismatch:
+
+```ruby
+RactorRailsShim.version_policy = :strict  # raise on untested versions
+RactorRailsShim.version_policy = :warn    # default: warn to $stderr, proceed
+RactorRailsShim.version_policy = :off     # silent (experimentation)
+```
+
+Under `:strict` a mismatch raises `RactorRailsShim::UnsupportedVersionError`.
+Each patch registers its tested Rails versions in `RactorRailsShim::PATCH_VERSIONS`;
+query what applied to your runtime with:
+
+```ruby
+RactorRailsShim.applicable_patches
+# => { applied: [:mattr_accessor, :rails_module, ...], skipped: [{name: ...}] }
+```
+
+Adding Rails 7.x support: the version-gated registry is the extension point —
+write version-specific patch variants, tag them in `PATCH_VERSIONS`, and the
+dispatcher applies only matching patches. (7.x is not yet supported; only 8.1
+is tested today.)
+
+## Install
+
+Add to your Gemfile:
+
+```ruby
+gem "ractor-rails-shim", group: :production
+```
+
+Then install early in boot, before `Rails.application` is first accessed:
+
+```ruby
+# config/boot.rb
+require "bundler/setup"
+require "ractor_rails_shim"
+RactorRailsShim.install
+```
+
+After Rails is fully booted (after `Rails.application.initialize!`) and **before
+spawning worker Ractors**, call `prepare_for_ractors!` to make the remaining
+unshareable constants (e.g. `Rails::Railtie::ABSTRACT_RAILTIES`, which loads
+after `module Rails` opens) shareable:
+
+```ruby
+# config/environment.rb, or wherever you boot your app before spawning workers
+Rails.application.initialize!
+RactorRailsShim.prepare_for_ractors!
+```
+
+To share the whole app across worker Ractors (the `:ractor` mode path), call
+`make_app_shareable!` — it replaces every self-capturing Proc in the app graph
+with a callable object, every Mutex/Monitor with a no-op lock, and every
+`Concurrent::Map` with a frozen Hash, then calls `Ractor.make_shareable`:
+
+```ruby
+Rails.application.initialize!
+app = RactorRailsShim.make_app_shareable!(Rails.application)
+# app is now frozen and Ractor.shareable? — pass it to worker Ractors:
+worker = Ractor.new(app) { |a| a.call(env) }
+```
+
+**Note:** `make_app_shareable!` is production-only (the app becomes read-only).
+It also **detaches the logger IO from the app graph**: `app.config.logger`
+(the broadcast target holding the real `$stdout`/`$stderr` IO) is swapped for a
+frozen no-op `BroadcastLogger` so `Ractor.make_shareable(app)` doesn't freeze
+the process's real IOs, and the main ractor's `Rails.logger` (the per-Ractor
+module accessor, not in the app graph) is re-pointed at a fresh live
+`BroadcastLogger` → `$stderr` so main keeps logging. Worker ractors build their
+own per-Ractor `Rails.logger` (a `BroadcastLogger` → `$stderr`). To fix
+unshareable constants in your own app/gems, add them to the registry before
+`prepare_for_ractors!`:
+
+```ruby
+RactorRailsShim.shareable_constants << "MyGem::MUTABLE_LIST"
+RactorRailsShim.prepare_for_ractors!
+```
+
+Or from a Rails console / runner for a quick check:
+
+```ruby
+require "ractor_rails_shim"
+RactorRailsShim.install
+```
+
+## Audit your app
+
+```sh
+bundle exec ractor-rails-check
+# or scoped:
+bundle exec ractor-rails-check --rails   # only Rails framework modules
+bundle exec ractor-rails-check --app     # only app + gems
+```
+
+Reports class ivars holding unshareable values — the ones that would raise `Ractor::IsolationError` from a worker Ractor. Example:
+
+```
+ractor-rails-shim check: 23 class-ivar blocker(s) found
+
+=== Rails framework (8) ===
+  Rails@application = nil
+  Rails@app_class = String
+  Rails@cache = NilClass
+  ...
+
+=== app + gems (15) ===
+  Devise@config = Devise::Config
+  Sidekiq@options = Hash
+  ...
+
+hints:
+  - require "ractor_rails_shim" and call RactorRailsShim.install before
+    Rails.application is first accessed (early in config/boot.rb)
+  - class-var (@@foo) blockers from mattr_accessor/cattr_accessor are rerouted
+    by the shim automatically once installed
+  - raw class-ivar (@foo) blockers are NOT fixed by the shim; patch the gem
+    or use Ractor.make_shareable + a constant for shareable state
+  - for per-Ractor mutable state use Ractor.store_if_absent(key) { default }
+```
+
+## What this fixes
+
+- `Rails.application`, `Rails.app_class`, `Rails.cache`, `Rails.logger`, `Rails.env`, `Rails.backtrace_cleaner` — rerouted through `IsolatedExecutionState`.
+- `Module.mattr_accessor` / `cattr_accessor` — the macro is rewritten so all ~150 call sites in Rails inherit the fix without individual edits. Pass `shareable: true` to opt an accessor into the shareable-by-reference path instead.
+- `Class.class_attribute` (ActiveSupport) — the macro is rewritten so `executor`, `check`, and every other `class_attribute`-defined accessor routes through `IsolatedExecutionState` via string-eval'd methods (no captured binding). Without this, a worker Ractor calling `app.reloader.executor = ...` during boot raises "defined with an un-shareable Proc in a different Ractor".
+- `Zeitwerk::Registry` class ivars (`@loaders`, `@mutex`, `@autoloads`, etc.) — routed through `IsolatedExecutionState` so a worker Ractor can create autoloaders (each Ractor gets its own registry).
+- Unshareable constants (`Rails::Railtie::ABSTRACT_RAILTIES`, `ActiveSupport::EnvironmentInquirer::DEFAULT_ENVIRONMENTS`, etc.) — made shareable once at boot via `Ractor.make_shareable` + `const_set`. Add your own via `RactorRailsShim.shareable_constants << "MyGem::CONST"` then call `prepare_for_ractors!`.
+- **Framework class config fallback** (`SHAREABLE_FALLBACK`) — at `make_app_shareable!` time the main ractor's live `class_attribute` / `mattr_accessor` values are captured, made shareable (callable-replacement for any Procs), and exposed as a read-only fallback. Worker readers return it when their per-Ractor IES slot is empty — this is what fixes `ActionController::Base.config` being nil in workers.
+- **Raw class-ivar/cvar accessors Rails reads per-request** (the long tail beyond `mattr_accessor`) — patched individually: `ExecutionWrapper.active_key`, `ActiveSupport::Notifications.notifier`, `ActiveSupport.error_reporter`, `ActiveSupport::ExecutionContext` (after_change_callbacks / nestable), `ActiveSupport::Inflector::Inflections`, `ActionView::PathRegistry`, `ActionView::LookupContext` + `DetailsKey` (`view_context_class` built per-controller in main & shared via `VIEW_CONTEXT_REGISTRY`), `ActionView::Template::Handlers`, `AbstractController::Base` (`controller_path` / `action_methods` / `abstract` / `_prefixes` via per-Ractor Hash caches keyed by class), `AbstractController::UrlFor#action_methods` (sidesteps the unshareable `_routes` define_method-block), `ActionController::ParameterEncoding#action_encoding_template`, `Rack::Request` (`forwarded_priority` / `x_forwarded_proto_priority`), `Rack::Utils` (`default_query_parser` / multipart limits), `ActionDispatch::Request.parameter_parsers`, `I18n::Config` (`default_locale` / `locale`) + `I18n.fallbacks` + `I18n::Locale::Tag.implementation`.
+- **`ActiveSupport::Callbacks#run_callbacks`** — made nil-safe so a worker Ractor whose `__callbacks` couldn't be shared (frozen, self-capturing-Proc callback chains) treats callbacks as empty. Correct for a read-only shared app where boot-time callbacks already ran in main.
+
+## What this does NOT fix
+
+- **Gems.** Every gem your app depends on (Devise, Sidekiq, redis-rb, pg, etc.) has its own class ivars. The shim's `mattr_accessor` rewrite helps gems that use that macro, but gems using raw `@ivar ||= ...` need their own patches. The `--check` script surfaces these.
+- **App code** holding mutable state in closures (`cache = {}; ->(env){ cache[...] }`). The shim can't see into closures; `--check` finds class ivars only.
+- **define_method-block methods.** A handful of Rails methods are defined via `define_method` with a block capturing the defining Ractor (e.g. `ActionDispatch::Routing::RouteSet`'s `_routes` singleton helper, `ActionView::Base.with_empty_template_cache`'s `compiled_method_container`). The shim works around these by building the affected classes (e.g. `view_context_class`) in the main Ractor and sharing them, or by reading the route set directly from the shared `Rails.application`. More complex apps may hit additional `define_method`-block call sites that need similar treatment.
+
+## Limitations
+
+- **Per-Ractor means N copies.** Each Ractor gets its own `Rails.application`, `Rails.cache`, etc. — same shape as forking N processes, but cheaper (no heap duplication). For large read-only state, use `Ractor.make_shareable` instead.
+- **The mattr_accessor rewrite is broad.** It reroutes *all* `mattr_accessor`-defined accessors through `IsolatedExecutionState`, including ones that were legitimately class-global. This may change semantics for code that sets a value in main Ractor expecting worker Ractors to see it. Audit with `--check` and use `shareable: true` for accessors that should be shared.
+- **Fragile across Rails versions.** This is a monkey-patch. Rails releases that touch `rails.rb` or `mattr_accessor` may break it. When upstream fixes it, delete the gem.
+
+## When to delete this gem
+
+This shim is a **stopgap**. Delete it (remove from the Gemfile) when Rails
+natively supports Ractor mode — i.e. when **all** of these land upstream:
+
+1. Class-level instance variables / class variables backing `mattr_accessor`
+   and `class_attribute` are migrated to `IsolatedExecutionState` (or
+   equivalent ractor-safe storage). Rails already does this for
+   `ActiveRecord::ConnectionHandling.connection_handler`, proving the pattern.
+2. The `Zeitwerk::Registry` class ivars route through ractor-safe storage.
+3. Unshareable constants (`EnvironmentInquirer::DEFAULT_ENVIRONMENTS`, etc.)
+   are made shareable (deep-frozen) at boot.
+ 4. The **7 self-capturing Procs** in the app graph are restructured to not
+    capture `self` — e.g. the `Rack::Files` head lambda, `ActionDispatch::SSL`
+    exclude proc, `CookieStore` same-site proc, the message-verifier secret
+    generator, and the routes-reloader blocks. These block
+    `Ractor.make_shareable(Rails.application)` today.
+5. Initializer blocks (`Rails::Initializable::Initializer#block`) are
+   shareable (defined as methods, not closures) so per-Ractor boot works.
+
+Until then, the shim is required. A simple canary: with the gem removed,
+`Ractor.make_shareable(Rails.application)` fails (it raises on a Mutex or a
+"Proc's self is not shareable"). When that call succeeds unshimmed, the gem
+is obsolete. See `UPSTREAM_ISSUE.md` for the full blocker map and the
+proposed incremental upstream merge plan.
+
+## Publishing (maintainers)
+
+The gemspec is publish-ready (metadata, MFA required, CHANGELOG packaged).
+To release a new version:
+
+```sh
+# Bump lib/ractor_rails_shim/version.rb and add a CHANGELOG entry, then:
+gem build ractor-rails-shim.gemspec
+gem push ractor-rails-shim-<version>.gem
+```
+
+CI (`.github/workflows/ci.yml`) gates merges: unit specs (no Rails) + an
+integration job that builds the minimal Rails 8.1 app and dispatches `GET /up`
+in a worker Ractor. Don't publish from a red build.
+
+## License
+
+MIT

data/exe/ractor-rails-check

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# ractor-rails-check — audit a loaded Rails app (or any Ruby app) for
+# class-level instance variables that would block Ractor mode.
+#
+# Usage:
+#   ractor-rails-check            # scan loaded modules, print report
+#   ractor-rails-check --rails    # only Rails framework modules
+#   ractor-rails-check --app      # only app + gems (exclude Rails)
+#
+# Typically run from a Rails console or a boot script:
+#   bundle exec rails runner ractor-rails-check
+
+require "ractor_rails_shim/check"
+
+scope = ARGV.find { |a| a.start_with?("--") }&.sub(/^--/, "")&.to_sym || :all
+
+case scope
+when :rails
+  findings = RactorRailsShim::Check.scan_rails
+when :app
+  findings = RactorRailsShim::Check.scan_app
+else
+  RactorRailsShim::Check.report(print: true)
+  exit 0
+end
+
+# Scoped report
+if findings.empty?
+  puts "no blockers found in scope :#{scope}"
+  exit 0
+end
+
+puts "=== scope :#{scope} (#{findings.size} blockers) ==="
+findings.each do |f|
+  puts "  #{f.owner}#{f.ivar} = #{f.value_class}"
+  puts "    #{f.source}" if f.source
+end

data/lib/ractor_rails_shim/check.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require_relative "version"
+
+module RactorRailsShim
+    # Audit an app for Ractor blockers. Inspects loaded classes/modules for
+    # class-level instance variables and mattr_accessor usage that would
+    # raise Ractor::IsolationError from a non-main Ractor.
+    #
+    # Modeled on Kino's `kino --check` — tell the user *exactly* what blocks
+    # their app, instead of leaving them to decode IsolationError at runtime.
+    class Check
+      # kind: :ivar (class-level instance variable, @foo) or
+      #      :cvar (class variable, @@foo — mattr_accessor/cattr_accessor)
+      Finding = Data.define(:owner, :ivar, :value_class, :shareable, :source, :kind)
+
+      class << self
+        # Scan all loaded classes/modules and report class ivars AND class
+        # variables holding unshareable values. Returns an array of Finding.
+        def scan
+          findings = []
+          seen = {}
+
+          ObjectSpace.each_object(Module) do |mod|
+            next if mod.name.nil? || mod.name.empty?
+            next if mod.name.start_with?("#", "Ractor::", "Thread::", "Fiber::", "ObjectSpace::")
+
+            # Inspect class-level instance variables.
+            mod.instance_variables.each do |ivar|
+              next if ivar == :@_sandbox # Rails internal, ignored
+              begin
+                val = mod.instance_variable_get(ivar)
+              rescue => e
+                next
+              end
+
+              shareable = begin
+                Ractor.shareable?(val)
+              rescue => e
+                false
+              end
+              next if shareable
+
+              key = "#{mod.name}#{ivar}"
+              next if seen[key]
+              seen[key] = true
+
+              source = locate(mod, ivar)
+              findings << Finding.new(
+                owner: mod.name,
+                ivar: ivar.to_s,
+                value_class: val.class.name || val.class.to_s,
+                shareable: shareable,
+                source: source,
+                kind: :ivar
+              )
+            end
+
+            # Inspect class variables (@@foo) — these back mattr_accessor /
+            # cattr_accessor and are ALSO subject to Ractor::IsolationError
+            # from non-main Ractors (verified on Ruby 4.0.5).
+            begin
+              mod.class_variables.each do |cvar|
+                begin
+                  val = mod.class_variable_get(cvar)
+                rescue => e
+                  next
+                end
+
+                shareable = begin
+                  Ractor.shareable?(val)
+                rescue => e
+                  false
+                end
+                next if shareable
+
+                key = "#{mod.name}#{cvar}"
+                next if seen[key]
+                seen[key] = true
+
+                source = locate(mod, cvar)
+                findings << Finding.new(
+                  owner: mod.name,
+                  ivar: cvar.to_s,
+                  value_class: val.class.name || val.class.to_s,
+                  shareable: shareable,
+                  source: source,
+                  kind: :cvar
+                )
+              end
+            rescue => e
+              # Some modules raise on class_variables enumeration; skip.
+              next
+            end
+          end
+
+          findings.sort_by { |f| [f.owner, f.ivar] }
+        end
+
+        # Scan only Rails framework modules (Railties, ActiveRecord, etc.)
+        # — the ones the shim targets. Useful for "is Rails itself clean?"
+        def scan_rails
+          scan.select { |f| f.owner.start_with?("Rails", "ActiveRecord", "ActiveSupport",
+            "ActionController", "ActionView", "ActionDispatch", "ActionMailer",
+            "ActiveJob", "ActionCable", "ActionText", "ActionMailbox", "ActiveStorage") }
+        end
+
+        # Scan app + gem classes outside the Rails framework.
+        def scan_app
+          scan - scan_rails
+        end
+
+        # Human-readable report. Returns a string; also prints to $stderr
+        # if `print:` is true (default).
+        def report(print: true)
+          findings = scan
+          rails_findings = findings.select { |f| rails_namespace?(f.owner) }
+          app_findings = findings - rails_findings
+
+          lines = []
+          cvar_count = findings.count { |f| f.kind == :cvar }
+          ivar_count = findings.count { |f| f.kind == :ivar }
+          lines << "ractor-rails-shim check: #{findings.size} blocker(s) found" \
+            " (#{ivar_count} class-ivar, #{cvar_count} class-var)"
+          lines << "  (unshareable values in @ivar and @@cvar; reads/writes from a non-main Ractor"
+          lines << "   would raise Ractor::IsolationError)"
+          lines << ""
+
+          %i[rails app].each do |group|
+            grp = group == :rails ? rails_findings : app_findings
+            next if grp.empty?
+
+            label = group == :rails ? "Rails framework" : "app + gems"
+            lines << "=== #{label} (#{grp.size}) ==="
+            grp.first(50).each do |f|
+              tag = f.kind == :cvar ? " (mattr/cattr — shim targets)" : ""
+              lines << "  #{f.owner}#{f.ivar} = #{f.value_class}#{tag}"
+              lines << "    #{f.source}" if f.source
+            end
+            if grp.size > 50
+              lines << "  ... and #{grp.size - 50} more (use Check.scan to see all)"
+            end
+            lines << ""
+          end
+
+          if findings.empty?
+            lines << "no blockers found — app may be Ractor-compatible"
+          else
+            lines << "hints:"
+            lines << "  - require \"ractor_rails_shim\" and call RactorRailsShim.install before"
+            lines << "    Rails.application is first accessed (early in config/boot.rb)"
+            lines << "  - class-var (@@foo) blockers from mattr_accessor/cattr_accessor are"
+            lines << "    rerouted by the shim automatically once installed"
+            lines << "  - raw class-ivar (@foo) blockers are NOT fixed by the shim; patch the"
+            lines << "    gem or use Ractor.make_shareable + a constant for shareable state"
+            lines << "  - for per-Ractor mutable state use Ractor.store_if_absent(key) { default }"
+          end
+
+          out = lines.join("\n")
+          $stderr.puts(out) if print
+          out
+        end
+
+        private
+
+        def rails_namespace?(name)
+          name.start_with?("Rails", "ActiveRecord", "ActiveSupport", "ActionController",
+            "ActionView", "ActionDispatch", "ActionMailer", "ActiveJob", "ActionCable",
+            "ActionText", "ActionMailbox", "ActiveStorage")
+        end
+
+        # Best-effort: locate where the ivar is set in source. Not always
+        # possible (set via mattr_accessor macro), but useful when it is.
+        def locate(mod, ivar)
+          # Check if it's a method-defined accessor (mattr_accessor etc.)
+          reader = ivar.to_s.delete("@").to_sym
+          if mod.singleton_class.method_defined?(reader)
+            m = mod.singleton_class.instance_method(reader)
+            if m.source_location
+              file, line = m.source_location
+              return "#{file}:#{line}"
+            end
+          end
+          nil
+        rescue => e
+          nil
+        end
+      end
+    end
+  end

data/lib/ractor_rails_shim/fallback_ies.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Fallback IsolatedExecutionState when ActiveSupport is not available.
+# This is a simple thread-local storage that mimics the ActiveSupport API
+# enough for the shim to work. In production (with Rails loaded), the real
+# ActiveSupport::IsolatedExecutionState is used instead.
+module ActiveSupport
+  module IsolatedExecutionState
+    KEY = :active_support_execution_state_fallback
+
+    class << self
+      def [](key)
+        Thread.current[KEY]&.[](key)
+      end
+
+      def []=(key, value)
+        (Thread.current[KEY] ||= {})[key] = value
+      end
+
+      def key?(key)
+        Thread.current[KEY]&.key?(key)
+      end
+
+      def delete(key)
+        Thread.current[KEY]&.delete(key)
+      end
+
+      def clear
+        Thread.current[KEY] = nil
+      end
+    end
+  end
+end unless defined?(ActiveSupport::IsolatedExecutionState)