ractor-rails-shim 0.2.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 267a3734452aa4069b68599b193d8bebd3fa6e386836ec9ec4238d9667f6b37a
-  data.tar.gz: 748ee127a59a4e7cc0b90b16ff7339edb2dfd6cde3b15df01c1ff29d910d05c3
+  metadata.gz: 21002fee5a30f663904441d8c016c035564095bf456048a25917657e9adab5fc
+  data.tar.gz: dcb6764139de152ae7b958112503efc7951d59ae211c04ee268da6bf63a2be51
 SHA512:
-  metadata.gz: fdd580e1b1c24d324dfc9067a323dff580acd612ac8cfc2551424d4d359d5fc93d55c7ae7a9825efecad3103ef2c59b1b481a34d9270471f23fd19747dc9a52c
-  data.tar.gz: '0523817853ccdfc9444c0815fcb943b7cb3f745519b5baf6683e269e60c81889f97500e7e9e34da7bd3da7e74a3fd3033c5bbd25c4de6296337735ed6fd8301c'
+  metadata.gz: 28cf75ae0f4972142cee3965d5c68fd8b70c09b901dc60c186f178ac403fc7695c3f7e2e77e4591c9aa6aa0fc9c6d1ba5eafa8e3c64d5abad545b50159159d6c
+  data.tar.gz: b1bf30685c4b7082c5930a63693571e4d3affff2fa0b530fd355aaf5a57f5cf42280ff5a590f099705e8af573ae953d654ace88fbb813dc05e463379fa0c09c7

data/CHANGELOG.md

@@ -7,6 +7,268 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0]
+
+### Changed — breaking (public API)
+- **`worker_app` renamed to `worker_app!`.** The factory freezes +
+  `Ractor.make_shareable`s the `WorkerApp` — a destructive build — so it
+  now carries the bang the naming convention reserves for "mutates /
+  produces a frozen shareable." Callers following the README's
+  `Ractor.new(worker_app) { |a| a.call(env) }` example must update to
+  `worker_app!`. The old name is gone. (`patches/core.rb`)
+
+- **`fix_url_helpers_singleton_routes` renamed to
+  `fix_url_helpers_singleton_routes!`.** Mutates the global routes
+  singleton; now bang-suffixed per the convention documented at the top
+  of `patches.rb`. (`patches/route_helpers.rb`)
+
+- **Tightened `activesupport` dependency to `>= 8.1`.** The gemspec
+  previously declared `>= 7.0`, but the shim only supports Rails 8.1
+  (per `Version::TESTED_RAILS` / `SUPPORTED_RAILS`). The looser bound let
+  Bundler resolve against AS 7.x where the class-layout patches
+  (`class_attribute`, `Callbacks`, `PathRegistry`, …) would silently miss
+  blockers or redefine the wrong methods. Bound at `>= 8.1` so Bundler
+  fails fast on an unsupported Rails. (`ractor-rails-shim.gemspec`)
+
+### Fixed
+- **`_apply_shareable_constants!` set the done-flag on undefined
+  constants.** It set `@shareable_constants_done = true` after the first
+  run unconditionally, even when registered constants didn't exist yet
+  (`make_constant_shareable` returned `false`). A later call (from
+  `make_app_shareable!` or `prepare_for_ractors!`) short-circuited on the
+  flag and never retried the now-loadable constants — workers then hit
+  `Ractor::IsolationError` on unshareable values (e.g.
+  `Rack::Utils::PATH_SEPS`, a Regexp not deep-frozen until
+  `make_shareable` runs on it). The flag now sets only when every
+  registered constant was made shareable; any `false` return leaves it
+  unset so the next call retries. Caught by the integration spec (boots
+  a real Rails 8.1 app, dispatches `GET /up` in a worker Ractor); pinned
+  by `apply_shareable_constants_retry_spec.rb`.
+
+- **ActionFilter private ivar reads now gated through the `_swallow`
+  debug funnel.** The eval'd `set_callback` interceptor inlined
+  `af.instance_variable_get(:@conditional_key) rescue nil`, but
+  `instance_variable_get` returns nil for a missing ivar *without*
+  raising — the rescue never fired, and a silent Rails internal rename
+  (`@conditional_key` / `@actions`) would leave `only`/`except` nil,
+  making callbacks run for actions they shouldn't (security-relevant)
+  with no visible cause. New `_read_action_filter_constraints(af)` checks
+  `instance_variable_defined?` and emits a labeled
+  `[ractor_rails_shim] action filter constraints: missing ivar …`
+  warning under `debug=true`. Returns `[nil, nil]` for a bare object,
+  `[key, symbols]` when the ivars are present.
+
+- **Dead ternary in thread-mode `class_attribute` reader.** The reader
+  carried `:__class_attr___callbacks == :__callbacks ? {} : nil`, but
+  the namespaced name is always `__class_attr_<name>` (never `<name>`),
+  so the check was always false — dead code that allocated a `Symbol`
+  via `inspect` on every read AND never delivered the intended `{}`
+  default for `__callbacks` (callers index the result, so `nil` would
+  `NoMethodError`). Replaced with a static decision based on the public
+  name, inlining the shared frozen `EMPTY_CALLBACKS_HASH` constant.
+
+- **Redundant `class_variable_set` pair in `mattr_accessor` writer.**
+  The shim-generated writer had two complementary guarded lines
+  (`set if defined?` + `set unless defined?`) that together were one
+  unconditional set, with a wasted `class_variable_defined?` per write.
+  Replaced with a single `class_variable_set(cv, val) if Ractor.main?`.
+
+- **`WorkerApp#setup_once!` race-spec cleanup leak.** The race spec's
+  `ensure` block restored `Thread::Mutex.new` via
+  `define_method { orig_new.call }`, leaving a block that captures a
+  main-Ractor-bound `Method`. When a later spec's worker Ractor called
+  `Thread::Mutex.new` it raised `IsolationError` (flaky
+  `WorkerAppSpec#test_0002`). Replaced with `remove_method(:new)` so the
+  call falls back to the class-defined `new` (no captured binding).
+
+### Changed
+- **Centralized `const_set`-with-suppressed-`$VERBOSE` into
+  `_reassign_shareable_const(name, value)`.** `SHAREABLE_FALLBACK`,
+  `SHAREABLE_MATTR_DEFAULTS`, `SHAREABLE_APP`, and
+  `SHAREABLE_DECLARED_CALLBACKS` were each rebuilt + reassigned via an
+  inlined `$VERBOSE = nil … const_set … ensure $VERBOSE = …` dance. The
+  dance now lives in one helper on `RactorRailsShim`; all rebuild sites
+  (including the 6 `activerecord.rb` sites + 1 `kaminari.rb` site) call
+  it. The constants stay frozen shareable `Hash`es (always readable from
+  any Ractor) — a mutable-then-frozen registry would not be shareable
+  until `freeze!`, breaking workers that read early.
+
+- **Callable/lock object model extracted to `patches/callables.rb`.**
+  `NoOpProc` / `Callable` / `CallableConst` / `DeviseMappingSnapshot` /
+  `NoOpLock` / `NoOpLogDev` + the `_devise_mapping_snapshot` helper moved
+  out of the 964-line `make_shareable.rb` into their own file. Plain
+  class definitions replace the string-eval indirection (the eval was
+  stylistic, not behavioral). `make_shareable.rb`: 964 → 822 lines.
+
+- **`VersionPolicy` module extracted from the `RactorRailsShim` god
+  module.** The version-policy + patch-registry concern (`:warn` /
+  `:strict` / `:off` switch, `PATCH_VERSIONS`, `_register_patch` /
+  `applicable_patches` / `_version_mismatch`) moved from the
+  `RactorRailsShim` singleton in `core.rb` to
+  `RactorRailsShim::VersionPolicy` (`version_policy.rb`). `core.rb` keeps
+  the public facade (`RactorRailsShim.version_policy`, `.applicable_patches`,
+  `::PATCH_VERSIONS`, `::UnsupportedVersionError`) delegating to the
+  module. Orthogonal to the already-extracted `RactorRailsShim::Version`
+  (detection).
+
+- **`mattr_accessor` split into single-responsibility helpers.** The
+  per-symbol body did four things (call super, push to `CLASS_ATTRIBUTES`,
+  seed the default + rebuild the shareable constant, redefine the
+  reader/writer). Extracted `_seed_mattr_default(key, default)` and
+  `_register_for_fallback(mod_name, sym, key, default)`; `mattr_accessor`
+  now reads `super, register, seed, redefine`.
+
+- **Thread-mode vs Ractor-mode `class_attribute` heredocs de-duplicated.**
+  Each branch inlined a near-identical ~25-line reader/writer heredoc,
+  differing only in the method name. Extracted
+  `_class_attr_thread_methods` / `_class_attr_ractor_methods` (each builds
+  one reader+writer pair); `redefine` calls the helper twice. One source
+  of truth per mode. Also fixed a misaligned `else` (12-space indent in a
+  10-space block). `class_attribute.rb`: 232 → 224 lines.
+
+- **Freeze-path bare rescues routed through the `_swallow` debug funnel.**
+  `_freeze_shareable_class_ivars!`, `_freeze_declared_callbacks!`,
+  `_collect_controller_classes`, `_replace_locks_and_concurrent_maps!`,
+  `_replace_one_proc`, `_neutralize_logger_io!`,
+  `DeviseMappingSnapshot`, `_devise_mapping_snapshot`, `_warm_journey_routes`,
+  url-helper freeze, `DUMMY_END_NODE`, `MimeNegotiation`, AR db-config
+  handlers, AR query transformers, devise mappings, and the view-context
+  fallback now emit a labeled `[ractor_rails_shim] <label>: …` line to
+  `$stderr` under `debug=true` instead of bare `rescue; nil`. Silent by
+  default (backward compatible).
+
+- **`fallback_ies.rb` moved into the `RactorRailsShim` namespace.** It
+  previously defined `ActiveSupport::IsolatedExecutionState` directly
+  inside the `ActiveSupport` namespace (guarded by `defined?`). Defining
+  an upstream-namespaced constant from a third-party gem is a
+  namespace-patch smell — if a future AS lazy-loads IES, load order
+  decides which definition wins. The fallback now lives at
+  `RactorRailsShim::FallbackIES` and is aliased onto
+  `ActiveSupport::IsolatedExecutionState` only when the real AS IES is
+  absent. The ~270 string-eval'd references across the patch files
+  resolve to the alias when AS is absent and to the real one when present.
+
+- **Stream-of-consciousness comments trimmed to one-line invariants.**
+  Working-notes-style comments that narrated history ("actually it IS a
+  constant holding…", "Pre-fix the traversals only handled…") replaced
+  with one-line invariant statements. The history is in git.
+
+### Documentation
+- **`WorkerApp#setup_once!` race comment corrected (again).** A prior
+  0.2.6 entry claimed `Ractor.current[:key] ||= Thread::Mutex.new` is
+  atomic in Ruby 4.0.6. It is NOT — `||=` is a read-then-write, and N
+  racing threads produce N distinct mutexes (verified by spec under a
+  widened window). The code is saved by (1) MRI's GIL serializing the
+  flag check inside `synchronize` and (2) `rebind_constants` /
+  `init_worker_ar_connections!` both being idempotent. Comment now states
+  the real contract + the escape hatch if either property changes. Two
+  specs pin the idempotency contract.
+
+## [0.2.6]
+
+### Fixed
+- **`WorkerApp` from `worker_app` not `Ractor.shareable?`.** The factory
+  returned a bare `WorkerApp` instance without freezing or making it
+  shareable, so any caller following the README's
+  `Ractor.new(worker_app) { |a| a.call(env) }` example would raise
+  `Ractor::IsolationError` at spawn. `worker_app` now freezes +
+  `Ractor.make_shareable`s the instance, enforcing the shareability
+  contract at the boundary instead of pushing it onto every caller.
+  (`patches/core.rb`)
+
+- **`Hash#compute_if_absent` nil-caching divergence from
+  `Concurrent::Map`.** The shim replaces `Concurrent::Map` instances in
+  the frozen app graph with plain `Hash`es (Concurrent::Map isn't
+  Ractor-shareable) and adds a compatible `compute_if_absent`. The
+  frozen-Hash branch used `IES[key] ||= yield`, which SKIPS nil results
+  — but `Concurrent::Map#compute_if_absent` STORES nil (verified: the
+  key is present after a nil-result block call), so the shim's
+  divergent semantics re-invoked the block on every subsequent lookup
+  for any cache slot whose computed value was nil. The frozen branch
+  now uses a two-level IES bucket (`slot[object_id][key]`) with a
+  proper `key?` presence check, matching `Concurrent::Map` exactly.
+  Also fixed: an existing key on a frozen Hash now returns without
+  invoking the block (was always treating the receiver as empty), and
+  per-Hash isolation is now keyed by `object_id` so two frozen hashes
+  with the same key don't collide. (`patches/core.rb`)
+
+- **Magic `line == 32` strategy dispatch replaced with identity check.**
+  The Proc-replacement pass distinguished
+  `ActionDispatch::Routing::Mapper::Constraints::SERVE` from `CALL` by
+  hard-coding the `source_location` line number (32). Any Rails patch
+  release that shifted the constant definitions by even one line would
+  silently swap the two strategies and break routing (a dispatcher
+  endpoint called as `app.call(req.env)` instead of `app.serve(req)`).
+  Replaced with an `equal?` check against the actual constants — the
+  value stored in `@strategy` IS the constant object (Rails assigns it
+  by reference), so identity is the robust identifier, independent of
+  source layout. Falls through to `NoOpProc` for an unknown Proc
+  (defensive; never mis-routes). Extracted into
+  `_strategy_replacement_for`. (`patches/make_shareable.rb`)
+
+- **`capture_app_constants` crash on non-Zeitwerk autoloaders.** The
+  method called `Rails.autoloaders.main` / `.once` directly, which
+  `NoMethodError`s for apps in classic-loader mode or with
+  `config.autoloaders = false` (the autoloaders object exists but
+  doesn't expose `main`/`once`). Now filters to the loaders that
+  actually expose `all_expected_cpaths` (the Zeitwerk introspection
+  API), and tolerates autoloaders objects that only respond to `each`.
+  Also fixed a pre-existing bug: the early-return path returned an
+  UNFROZEN map, violating the method's documented frozen-map contract.
+  (`patches/core.rb`)
+
+### Changed
+- **`_replace_unshareable_procs!` 3.times magic replaced with a
+  fixed-point loop.** The original `3.times` had no justification and
+  an arbitrary constant. Replaced with a loop-to-fixed-point (break
+  when `_collect_procs` returns empty) plus a safety cap of 8 passes
+  to guard against a pathological graph where replacement keeps
+  introducing new Procs (the replacements are `NoOpProc`/`Callable`,
+  not `Proc`, so this shouldn't happen, but the cap prevents an
+  infinite loop). Documented the multi-occurrence rationale (the same
+  Proc object can live in many containers, e.g. shared deprecation
+  behaviors). Observed real graphs converge in 2 passes.
+  (`patches/make_shareable.rb`)
+
+- **Graph traversals now walk Set/Struct/Enumerable.**
+  `_collect_procs` and `_replace_locks_and_concurrent_maps!` only
+  handled `Array` and `Hash` as recursive containers. Rails uses `Set`
+  in several caches (e.g. `ActionDispatch::Journey::Routes`), and
+  `Struct`/`Enumerable` mixes appear in framework internals — a
+  `Mutex` or `Proc` nested inside one of those was missed and left
+  unshareable, breaking `make_app_shareable!` downstream. Extracted
+  `_each_ivar_and_child` (single responsibility: enumerate every child
+  reference of an object) shared by both traversals, handling `Hash`,
+  `Array`, `Set`, `Struct`, and a generic `Enumerable` fallback
+  (`Range`, `Enumerator`, custom mixins). The `Hash#default_proc`
+  branch is preserved so `_collect_procs` still flags default-proc
+  Procs. (`patches/make_shareable.rb`)
+
+### Added
+- **Debug funnel for freeze-path silent rescues.** The
+  freeze/shareability paths (`_freeze_active_record_class_ivars!`,
+  `_freeze_global_class_ivars!`, `_make_value_shareable`) rescue all
+  exceptions silently with bare `rescue; nil`. Individual failures are
+  expected (some ivars hold intrinsically unshareable values like
+  Procs), but a worker Ractor that later crashes on the same
+  unshareable value had no traceable cause. New `_swallow(label) { ... }`
+  funnel is silent by default (preserves backward compat) and emits a
+  labeled `[ractor_rails_shim] <label>: <class>: <msg>` line to
+  `$stderr` when `RactorRailsShim.debug = true`. The three freeze-path
+  rescues are routed through it; the bare rescues in non-freeze paths
+  (require `LoadError`, optional `const_get`, etc.) are left as-is —
+  those are genuinely expected and a `$stderr` line would be noise.
+  (`patches/core.rb`)
+
+### Documentation
+- **`WorkerApp#setup_once!` race comment corrected.** The previous
+  comment claimed `Ractor.current[:key] ||= Thread::Mutex.new` was racy
+  under "extreme contention" and dismissed it as harmless because the
+  init steps are idempotent. Verified on Ruby 4.0.6 that
+  `Ractor.current[:key] ||= X` is atomic (100 concurrent threads
+  produce exactly one mutex object), so the TOCTOU race does not
+  occur. Replaced the misleading comment with the verified finding.
+
 ## [0.2.5]
 
 ### Fixed

data/README.md

@@ -4,31 +4,34 @@ A monkey-patch shim that reroutes Rails' class-level instance variable accessors
 
 **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 **official Ruby 4.0.6**, 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.).
+**Current status (v0.2.5):** on a full Rails 8.1 app (Devise 5, Propshaft,
+Kaminari, PG) under **official Ruby 4.0.6**, 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.). 61 unit specs across 7
+spec files pass (no Rails dependency); an integration spec dispatches `GET /up`
+→ 200 in a worker Ractor.
 
 **No patched Ruby or kino required.** Official Ruby 4.0.6 ships the frozen-iseq
 call-cache fix (#22075) and the cross-ractor env-string fix, so the SIGBUS crashes
 that previously required the DDKatch patched Ruby/kino forks are resolved in core.
 Both SIGBUS classes were the only reason a patched build was ever needed; on 4.0.6
-the shim runs `kino -m ractor` on the official `kino` gem under sustained read
-**and** write load (verified: 0 transport failures / 0 server errors across
+the shim runs `kino -m ractor` on the official `kino` gem (0.1.3) under sustained
+read **and** write load (verified: 0 transport failures / 0 server errors across
 `/up`, `GET /posts`, `POST /posts` in the benchmark matrix).
 
 ## 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.
+- **Ruby >= 4.0.6** — the shim relies on Ruby 4.0's Ractor semantics and
+  `Ractor.make_shareable`, plus the frozen-iseq call-cache fix (#22075) and
+  the cross-ractor env-string fix that both shipped in 4.0.6. 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).
 
@@ -43,12 +46,71 @@ the configuration it is verified against.
 [kino](https://github.com/yaroslav/kino) (`kino -m ractor`). On official Ruby
 4.0.6 the **upstream `kino` gem (0.1.3) works as-is** — no fork or patch is
 required. (Historically a DDKatch/kino fork carried a per-ractor env-string
-cache fix; that fix is in official 4.0.6, so the fork is obsolete.)
+cache fix; that fix landed in official 4.0.6, so the fork is obsolete.)
+
+**Threaded servers (Puma/Falcon/Thin/Webrick):** set
+`RactorRailsShim.thread_mode = true` (or `ENV["SERVER"]` to one of
+`puma|falcon|thin|webrick|thread*`) and the shim installs a **minimal**
+patch set — only the `class_attribute` isolation fix + nil-safe callback
+replay. The per-Ractor IES-routing patches are skipped because IES is empty
+on a thread server's request threads and would break the app; Rails' own
+class globals are thread-safe and used as-is. Use this when you want the
+callback-correctness fixes without running in Ractor mode.
 
 **Benchmarks:** throughput/latency/memory of this shim + the test app under
 kino `:ractor` vs Puma vs Falcon are documented in
 [ractor-rails-shim-test-app/BENCHMARKS.md](https://github.com/DDKatch/ractor-rails-shim-test-app/blob/main/BENCHMARKS.md).
 
+## Repository layout
+
+```
+lib/ractor_rails_shim.rb            # entry point — autoload-install if Rails is loaded
+lib/ractor_rails_shim/
+  version.rb                        # VERSION constant (currently 0.2.5)
+  version_check.rb                  # Gem::Version-based Ruby/Rails detection + policy
+  fallback_ies.rb                   # thread-local IES shim when ActiveSupport is absent
+  check.rb                          # the ractor-rails-check audit (Check.scan / report)
+  patches.rb                        # requires all per-concern patch files in order
+  patches/
+    core.rb                         # module skeleton, registries, install, prepare_for_ractors!, WorkerApp
+    make_shareable.rb               # make_app_shareable!, callable/lock replacement, shareable fallback
+    rails_module.rb                 # Rails.application / Rails.cache / Rails.logger / Rails.env …
+    mattr_accessor.rb               # Module#mattr_accessor / cattr_accessor macro rewrite
+    class_attribute.rb              # ActiveSupport class_attribute macro rewrite
+    zeitwerk_registry.rb            # Zeitwerk::Registry class ivars
+    route_helpers.rb                # ActionDispatch::Routing::RouteSet#generate_url_helpers
+    url_helpers.rb                  # URL helper singleton + module fixes
+    execution_wrapper.rb            # ActiveSupport::ExecutionWrapper + callback replay
+    rack.rb                         # Rack::Request / Rack::Utils
+    action_view.rb                  # PathRegistry, LookupContext, Template handlers, compiled_method_container
+    action_controller.rb            # AbstractController, ActionController name/encoding
+    action_dispatch.rb              # ActionDispatch routing, http_url, journey, mounted helpers
+    polymorphic_routes.rb           # polymorphic_path(s) URL helpers
+    active_support.rb               # Inflector, error_reporter, ExecutionContext, I18n, JSON encoding, Reloader
+    warden.rb                       # Warden hooks / strategies / serializer
+    devise.rb                       # Devise url_helpers / authenticatable / failure_app
+    active_model_attribute.rb       # ActiveModel::Attribute dup_or_share for frozen graphs
+    active_record_model_schema.rb   # AR ModelSchema reload_schema_from_cache (worker-safe)
+    activerecord.rb                 # AR connection handler, configurations, query caches, …
+    kaminari.rb                     # Kaminari config
+    propshaft.rb                    # Propshaft asset server
+    orm_adapter.rb                  # orm_adapter
+    openssl.rb                      # OpenSSL digest cache
+    rubygems.rb                     # Rubygems msgpack pre-check
+exe/ractor-rails-check              # CLI audit tool
+spec/                               # 7 spec files, 61 unit tests (no Rails dep) + integration spec
+script/make_test_app.sh             # build the minimal Rails 8.1 test app (CI uses this)
+script/make_full_test_app.sh        # build the full-featured test app (Devise/PG/Kaminari)
+.github/workflows/ci.yml            # unit job + integration job (GET /up → 200 in a worker Ractor)
+```
+
+Per-concern patch files reopen `RactorRailsShim`'s singleton class to add
+their `_install_*` methods. `patches.rb` requires them in dependency order
+(`core.rb` first — it defines the module skeleton + registries the rest
+reference). Each `_install_*` method is idempotent (guarded by its own
+`@*_patched` flag), so `install`, `prepare_for_ractors!`, and
+`make_app_shareable!` can all call the full set safely.
+
 ## Why
 
 Rails stores global state in class-level instance variables:

data/lib/ractor_rails_shim/fallback_ies.rb

@@ -1,11 +1,16 @@
 # 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
+#
+# The shim's string-eval'd patch methods reference the literal constant
+# `ActiveSupport::IsolatedExecutionState` (no captured binding → callable
+# from any Ractor). To avoid opening the ActiveSupport namespace from a
+# third-party gem, the fallback is defined in the shim's own namespace
+# (RactorRailsShim::FallbackIES) and aliased onto
+# ActiveSupport::IsolatedExecutionState only when the real AS IES is absent.
+# When AS is loaded, the real one wins untouched and no alias is created.
+module RactorRailsShim
+  module FallbackIES
     KEY = :active_support_execution_state_fallback
 
     class << self
@@ -30,4 +35,13 @@ module ActiveSupport
       end
     end
   end
-end unless defined?(ActiveSupport::IsolatedExecutionState)
+end
+
+# Alias onto ActiveSupport::IsolatedExecutionState only when the real AS IES
+# is absent, so the shim's string-eval'd references resolve to the fallback
+# without the shim opening the ActiveSupport namespace to define a module.
+unless defined?(ActiveSupport::IsolatedExecutionState)
+  module ActiveSupport
+    IsolatedExecutionState = RactorRailsShim::FallbackIES
+  end
+end

data/lib/ractor_rails_shim/patches/action_dispatch.rb

@@ -293,7 +293,7 @@ module RactorRailsShim
       # while the objects are still mutable) populates the ivars so the frozen,
       # shared copies already hold the values and workers only read them.
       if Ractor.main? && defined?(::Rails) && ::Rails.application
-        begin
+        _swallow("warm journey routes") do
           rset = ::Rails.application.routes
           all = []
           all.concat(rset.named_routes.send(:routes).values) rescue nil
@@ -310,8 +310,6 @@ module RactorRailsShim
             p.required_names rescue nil
             p.optional_names rescue nil
           end
-        rescue
-          nil
         end
       end
       # Capture the (shareable) RouteSet so workers can build URLs without
@@ -422,15 +420,15 @@ module RactorRailsShim
         nrc.alias_method(:define_url_helper_without_shim, :define_url_helper)
       end
       nrc.define_method(:define_url_helper) do |mod, name, helper, url_strategy|
-        begin
-          # Detach the helper from the live route object before deep-freezing
-          # it for cross-Ractor sharing. The non-optimized UrlHelper#call only
-          # needs @options / @segment_keys / @route_name to build the options
-          # hash and then delegates to `t._routes.url_for(route_name, ...)`,
-          # which looks the route up in the (shareable) RouteSet by name. The
-          # @route reference would pull the whole route graph into the freeze,
-          # freezing objects that make_app_shareable! must still be able to
-          # mutate (e.g. Devise route constraints) -> FrozenError.
+        # Detach the helper from the live route object before deep-freezing
+        # it for cross-Ractor sharing. The non-optimized UrlHelper#call only
+        # needs @options / @segment_keys / @route_name to build the options
+        # hash and then delegates to `t._routes.url_for(route_name, ...)`,
+        # which looks the route up in the (shareable) RouteSet by name. The
+        # @route reference would pull the whole route graph into the freeze,
+        # freezing objects that make_app_shareable! must still be able to
+        # mutate (e.g. Devise route constraints) -> FrozenError.
+        RactorRailsShim._swallow("freeze url helper") do
           if helper.respond_to?(:instance_variable_get)
             helper.instance_variable_set(:@route, nil) rescue nil
             opts = helper.instance_variable_get(:@options)
@@ -439,8 +437,6 @@ module RactorRailsShim
             helper.instance_variable_set(:@segment_keys, segs.dup.freeze) rescue nil
           end
           helper = Ractor.make_shareable(helper)
-        rescue
-          nil
         end
         RactorRailsShim::URL_HELPERS[name] = helper
         strategy_const = url_strategy.equal?(::ActionDispatch::Routing::RouteSet::PATH) ?
@@ -705,7 +701,7 @@ module RactorRailsShim
       if defined?(::ActionDispatch::Journey::GTG::Builder) &&
          ::ActionDispatch::Journey::GTG::Builder.const_defined?(:DUMMY_END_NODE)
         node = ::ActionDispatch::Journey::GTG::Builder.const_get(:DUMMY_END_NODE)
-        Ractor.make_shareable(node) rescue nil
+        _swallow("make journey dummy end node shareable") { Ractor.make_shareable(node) }
       end
     end
 
@@ -787,7 +783,7 @@ module RactorRailsShim
         next unless c.is_a?(::Array) || c.is_a?(::Hash)
         next if c.frozen?
         c.freeze
-        ::Ractor.make_shareable(c) rescue nil
+        _swallow("make mime negotiation constant shareable") { ::Ractor.make_shareable(c) }
       end
     rescue => e
       warn "[ractor-rails-shim] _freeze_mime_negotiation!: #{e.class}: #{e.message}"

data/lib/ractor_rails_shim/patches/action_view.rb

@@ -244,7 +244,7 @@ module RactorRailsShim
           (defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application) ? ::Rails.application.routes : nil,
           nil
         )
-        Ractor.make_shareable(fallback) rescue nil
+        fallback = _swallow("make view context fallback shareable") { Ractor.make_shareable(fallback) }
         self._view_context_fallback = fallback
       end
 

data/lib/ractor_rails_shim/patches/activerecord.rb

@@ -199,12 +199,7 @@ module RactorRailsShim
         end
         snapshot.freeze
         Ractor.make_shareable(snapshot)
-        verbose, $VERBOSE = $VERBOSE, nil
-        begin
-          const_set(:AR_CONFIGURATIONS_SNAPSHOT, snapshot)
-        ensure
-          $VERBOSE = verbose
-        end
+        _reassign_shareable_const(:AR_CONFIGURATIONS_SNAPSHOT, snapshot)
       rescue => e
         # Best-effort; if we can't capture configs, workers won't be able
         # to auto-init connections. They can call init_worker_ar_connections!
@@ -459,12 +454,7 @@ module RactorRailsShim
           pk_map[n] = pk if pk
         end
         shareable = Ractor.make_shareable(pk_map)
-        verbose, $VERBOSE = $VERBOSE, nil
-        begin
-          const_set(:AR_PRIMARY_KEYS_SHAREABLE, shareable)
-        ensure
-          $VERBOSE = verbose
-        end
+        _reassign_shareable_const(:AR_PRIMARY_KEYS_SHAREABLE, shareable)
       rescue => e
         # best-effort
       end
@@ -916,12 +906,7 @@ module RactorRailsShim
           cfg = ::ActiveRecord::Base.configurations
           cfg = Ractor.make_shareable(cfg) if cfg
           if cfg
-            verbose, $VERBOSE = $VERBOSE, nil
-            begin
-              const_set(:AR_CONFIGURATIONS_SHAREABLE, cfg)
-            ensure
-              $VERBOSE = verbose
-            end
+            _reassign_shareable_const(:AR_CONFIGURATIONS_SHAREABLE, cfg)
           end
         rescue => e
           # best-effort
@@ -977,14 +962,9 @@ module RactorRailsShim
           handlers = ::ActiveRecord::DatabaseConfigurations.db_config_handlers
           # Make each handler Proc shareable (freezes its binding). A shareable
           # Proc is callable from any Ractor.
-          handlers.each { |h| Ractor.make_shareable(h) rescue nil }
+          handlers.each { |h| _swallow("make ar db config handler shareable") { Ractor.make_shareable(h) } }
           shareable = Ractor.make_shareable(handlers.dup)
-          verbose, $VERBOSE = $VERBOSE, nil
-          begin
-            const_set(:AR_DB_CONFIG_HANDLERS_SHAREABLE, shareable)
-          ensure
-            $VERBOSE = verbose
-          end
+          _reassign_shareable_const(:AR_DB_CONFIG_HANDLERS_SHAREABLE, shareable)
         rescue => e
           # best-effort
         end
@@ -1031,14 +1011,9 @@ module RactorRailsShim
       if Ractor.main?
         begin
           transformers = ::ActiveRecord.query_transformers
-          transformers.each { |t| Ractor.make_shareable(t) rescue nil }
+          transformers.each { |t| _swallow("make ar query transformer shareable") { Ractor.make_shareable(t) } }
           shareable = Ractor.make_shareable(transformers.dup)
-          verbose, $VERBOSE = $VERBOSE, nil
-          begin
-            const_set(:AR_QUERY_TRANSFORMERS_SHAREABLE, shareable)
-          ensure
-            $VERBOSE = verbose
-          end
+          _reassign_shareable_const(:AR_QUERY_TRANSFORMERS_SHAREABLE, shareable)
         rescue => e
           # best-effort
         end
@@ -1085,12 +1060,7 @@ module RactorRailsShim
           begin
             val = ::ActiveRecord.public_send(method_name)
             shareable = Ractor.make_shareable(val.is_a?(::Array) ? val.dup : val)
-            verbose, $VERBOSE = $VERBOSE, nil
-            begin
-              const_set(const_name, shareable)
-            ensure
-              $VERBOSE = verbose
-            end
+            _reassign_shareable_const(const_name, shareable)
           rescue => e
             # best-effort
           end