ractor-rails-shim 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21002fee5a30f663904441d8c016c035564095bf456048a25917657e9adab5fc
-  data.tar.gz: dcb6764139de152ae7b958112503efc7951d59ae211c04ee268da6bf63a2be51
+  metadata.gz: 6ebcbda319623aa7003caf170774074e19fdf2d6452ed086fbc5edbfec037fa5
+  data.tar.gz: 7ab60400652444ccbc5ca39ac403d387c156cc8a6178700f10c9d744db9c3fad
 SHA512:
-  metadata.gz: 28cf75ae0f4972142cee3965d5c68fd8b70c09b901dc60c186f178ac403fc7695c3f7e2e77e4591c9aa6aa0fc9c6d1ba5eafa8e3c64d5abad545b50159159d6c
-  data.tar.gz: b1bf30685c4b7082c5930a63693571e4d3affff2fa0b530fd355aaf5a57f5cf42280ff5a590f099705e8af573ae953d654ace88fbb813dc05e463379fa0c09c7
+  metadata.gz: 69433fe039a2e2bea0302e13117a0ba701b786eaaec6e2e636d1d4786d74428e11701db2c703bc6fdb10c698febb6d5bce646adba24011513802d76de237349f
+  data.tar.gz: 615e99053521f65e7aa013d8a5c23e97991bd8b3f8593a92c9c2cf57e2ab245796bde664731ac943fe6b52681a8416c4bddac9635a7c5be6b2c3cc6339ecbdd2

data/README.md

@@ -64,49 +64,123 @@ kino `:ractor` vs Puma vs Falcon are documented in
 ## Repository layout
 
 ```
-lib/ractor_rails_shim.rb            # entry point — autoload-install if Rails is loaded
+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)
+  version.rb                              # VERSION constant (currently 0.3.0)
+  loader.rb                               # pure require hub — one file, one job (POODR §1)
+  patches.rb                              # backward-compat redirect → loader.rb
+
+  foundation/                             # Layer 2: no internal deps
+    funnel.rb                             #   debug-aware exception-swallowing role
+    registry.rb                           #   canonical home for the nine shared registries
+    storage.rb                            #   pluggable key-value store contract (IES / ThreadLocal)
+    storage_strategy.rb                   #   composed Ractor/Thread strategy for class_attribute
+    ies_accessor.rb                       #   3-tier IES lookup pattern generator
+    const_reassign.rb                     #   $VERBOSE-suppressed const_set utility
+    version_check.rb                      #   Gem::Version-based Ruby/Rails detection
+    version_policy.rb                     #   mismatch policy (:warn/:strict/:off) + patch registry
+    run_mode.rb                           #   thread vs Ractor mode decision
+    role_defaults.rb                      #   DRY mixin for shared default-proc patterns
+
+  roles/                                  # Layer 3: depend on foundation
+    lifecycle.rb                          #   prepare_for_ractors! orchestration
+    installer.rb                          #   install orchestrator + framework-patch dispatcher
+    install_strategy.rb                   #   per-mode install bodies (Ractor / Thread)
+    pre_spawn_steps.rb                    #   shared orchestration steps
+    ar_model_walker.rb                    #   ActiveRecord model enumeration
+    constant_shareabilizer.rb             #   constant shareability
+    shareability_traversal.rb             #   app-graph traversal
+    callback_capture.rb                   #   callback-declaration capture
+    fallback_builder.rb                   #   shareable-fallback builder
+    worker_app.rb                         #   shareable Rack wrapper (per-worker init)
+    worker_app_factory.rb                 #   shareable-Rack-app factory
+    app_shareabilizer.rb                  #   make_app_shareable! orchestrator
+    freezers.rb                           #   freeze/warm sub-domain (6 freezer roles)
+    logger_io_neutralizer.rb              #   logger IO detachment
+    fallback_ies.rb                       #   backward-compat alias → Storage::ThreadLocal
+    check.rb                              #   ractor-rails-check audit (Check.scan / report)
+
+  patches/                                # Layer 4: monkey-patches (depend on roles + foundation)
+    core.rb                               #   module skeleton, registries, facade delegations
+    callables.rb                          #   NoOpProc, Callable, CallableConst, RequestCallable, …
+    make_shareable.rb                     #   make_app_shareable!, proc/lock replacement
+    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
+    action_controller.rb                  #   AbstractController, ActionController name/encoding
+    action_dispatch.rb                    #   ActionDispatch routing, http_url, journey
+    polymorphic_routes.rb                 #   polymorphic_path(s) URL helpers
+    active_support.rb                     #   Inflector, error_reporter, ExecutionContext, I18n, JSON
+    i18n.rb                               #   I18n locale/fallback patches
+    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
+    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
+    hash_compute_if_absent.rb             #   Hash#compute_if_absent for Concurrent::Map replacement
+
+exe/ractor-rails-check                    # CLI audit tool
+spec/                                     # 724 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)
 ```
 
+### Architecture: layered, POODR-aligned design
+
+The directory structure mirrors the dependency layers:
+
+```
+Layer 1: Entry        ractor_rails_shim.rb, loader.rb
+Layer 2: Foundation   foundation/  (no internal deps)
+Layer 3: Roles        roles/       (depend on foundation)
+Layer 4: Patches      patches/     (depend on roles + foundation)
+```
+
+The gem follows **Practical Object-Oriented Design in Ruby** (POODR) principles:
+
+- **SRP (§1):** Every file defines exactly one concern. `loader.rb` is a pure
+  require hub (no logic). `lifecycle.rb` owns `prepare_for_ractors!` orchestration.
+  Role objects (`Funnel`, `Registry`, `CallbackCapture`, etc.) each own one
+  responsibility.
+
+- **Dependencies (§2):** Role objects receive collaborators via `configure` seams
+  (keyword arguments), defaulting to facade lookups. No role reaches past its
+  own namespace by name — the composition root (`Installer`) is the one place
+  allowed to resolve by name.
+
+- **Interfaces (§3):** The `Storage` contract (`[]`, `[]=`, `key?`, `delete`)
+  is implemented by `Storage::IES` and `Storage::ThreadLocal`. The
+  `StorageStrategy` contract (`lookup`, `store`, `replay_callbacks?`,
+  `replay_callbacks!`) is implemented by `StorageStrategy::Ractor` and
+  `StorageStrategy::Thread`.
+
+- **Duck Typing (§4):** `ShareabilityTraversal` uses a `CONTAINER_WALKERS`
+  dispatch table (Hash → lambda) instead of `is_a?` chains. Lock detection
+  uses `respond_to?(:synchronize)` instead of `is_a?(Mutex)`.
+
+- **Composition (§5):** `AppShareabilizer` composes 15 collaborators via the
+  configure seam. `FallbackBuilder` uses a `ValueLookup` chain of responsibility.
+  `Installer` selects between `InstallStrategy::Ractor` and `InstallStrategy::Thread`.
+
+- **Roles (§6):** Modules as roles (`Funnel`, `ARModelWalker`,
+  `ConstantShareabilizer`, `CallbackCapture`, etc.) — each `extend RoleDefaults`
+  for DRY default-proc patterns.
+
 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
+their `_install_*` methods. `loader.rb` requires them in dependency order
+(`core.rb` first — it defines the module skeleton + constants that others
 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.

data/lib/ractor_rails_shim/foundation/const_reassign.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# ConstReassign (Issue #46 Step 46.2): the $VERBOSE-suppressed const_set
+# utility extracted from the facade's _reassign_shareable_const.
+#
+# The facade's _reassign_shareable_const calls ConstReassign.call, then
+# updates Registry for the four known registries (SHAREABLE_FALLBACK,
+# SHAREABLE_MATTR_DEFAULTS, ABSTRACT_REGISTRY, VIEW_CONTEXT_REGISTRY).
+# Role objects (CallbackCapture, FallbackBuilder, AppShareabilizer) inject
+# ConstReassign.method(:call) directly via the configure seam.
+
+module RactorRailsShim
+  module ConstReassign
+    # Set a constant on target_module with $VERBOSE suppressed.
+    # Returns the new value.
+    def self.call(target_module, name, value)
+      verbose, $VERBOSE = $VERBOSE, nil
+      begin
+        target_module.const_set(name, value)
+      ensure
+        $VERBOSE = verbose
+      end
+      value
+    end
+  end
+end

data/lib/ractor_rails_shim/foundation/funnel.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Funnel: the debug-aware exception-swallowing role extracted from the
+# RactorRailsShim god module (Issue #31, step 31.1d; POODR §1 SRP).
+#
+# Owns the `swallow(label) { block }` contract: run the block, rescue
+# StandardError, emit a labeled $stderr line when `debug?` is true,
+# return nil on failure. Used by freeze/shareability paths where
+# individual failures are expected (some ivars hold intrinsically
+# unshareable values like Procs) but a worker crash on the same value
+# later has no visible cause.
+#
+# `debug?` / `debug=` are the configuration seam. The facade
+# `RactorRailsShim.debug?` / `debug=` delegate here so existing specs
+# keep passing; role objects (ARModelWalker, LoggerIONeutralizer) reach
+# the funnel via `configure(funnel:)`, defaulting to `Funnel.method(:swallow)`.
+
+module RactorRailsShim
+  module Funnel
+    @debug = nil
+
+    class << self
+      # When true, swallowed exceptions are reported to $stderr so a worker
+      # Ractor that later crashes on an unshareable value has a traceable
+      # cause. Default false (silent, the historical behaviour).
+      def debug?
+        defined?(@debug) ? @debug : false
+      end
+
+      def debug=(value)
+        @debug = value
+      end
+
+      # Swallow an exception raised by the block, optionally logging it
+      # when `debug?` is on. `label` identifies the call site (e.g.
+      # "freeze AR ivar Post@column_defaults"). Keep the label short —
+      # it's only for grepping. Returns the block's value on success,
+      # nil on rescued StandardError.
+      def swallow(label)
+        yield
+      rescue StandardError => e
+        warn "[ractor_rails_shim] #{label}: #{e.class}: #{e.message[0, 120]}" if debug?
+        nil
+      end
+    end
+  end
+end

data/lib/ractor_rails_shim/foundation/ies_accessor.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# IESAccessor (Issue #45): generates reader/writer methods via the 3-tier
+# IES lookup pattern. Extracts the repeated accessor boilerplate from
+# patches/active_support.rb (20+ accessor patches that all follow the
+# same shape).
+#
+# The generated methods use StorageStrategy for the actual lookup/store,
+# so they inherit both Ractor-mode and Thread-mode behavior without
+# duplicating the lookup logic.
+#
+# Usage:
+#   RactorRailsShim::IESAccessor.define_accessor(
+#     ActiveSupport::Inflector::Inflections,
+#     :instance,
+#     :ractor_rails_shim_inflections_en
+#   )
+#
+# This generates a reader (`instance`) and writer (`instance=`) on the
+# target class that do the 3-tier lookup:
+#   1. IES (per-Ractor IsolatedExecutionState)
+#   2. SHAREABLE_FALLBACK (frozen config captured at prepare time)
+#   3. main-Ractor default (CLASS_ATTR_VALUES or nil)
+
+module RactorRailsShim
+  module IESAccessor
+    # Generate a reader method on `target` that does the 3-tier lookup.
+    # `target` is a Class or Module. `attr_name` is the method name (Symbol).
+    # `ies_key` is the storage key (Symbol).
+    def self.define_reader(target, attr_name, ies_key)
+      key_str = ies_key.inspect
+      target.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{attr_name}
+          strategy = RactorRailsShim.storage_strategy
+          strategy.lookup(self, #{key_str}, nil)
+        end
+      RUBY
+    end
+
+    # Generate a writer method on `target` that stores via storage_strategy.
+    def self.define_writer(target, attr_name, ies_key)
+      key_str = ies_key.inspect
+      target.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{attr_name}=(val)
+          strategy = RactorRailsShim.storage_strategy
+          strategy.store(self, #{key_str}, val)
+          val
+        end
+      RUBY
+    end
+
+    # Generate both reader and writer on `target`.
+    def self.define_accessor(target, attr_name, ies_key)
+      define_reader(target, attr_name, ies_key)
+      define_writer(target, attr_name, ies_key)
+    end
+  end
+end

data/lib/ractor_rails_shim/foundation/registry.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# Registry: the canonical home for the shared registries that every role
+# object reads/writes (Issue #25, POODR §1 SRP + §2 Dependencies).
+#
+# Issue #35 (Round 4): Registry OWNS the nine registries as instance
+# variables. The facade constants in patches/core.rb are aliases that
+# delegate to Registry. Reassignment of the frozen (shareable) registries
+# goes through Registry.reassign_* so the facade alias tracks the new
+# value without a $VERBOSE-suppressed const_set on the facade.
+#
+# Types:
+#   - Mutable Array: class_attributes, shareable_constants, shareable_class_ivars
+#   - Mutable Hash:  mattr_defaults, class_attr_values, shareable_mattr_defaults
+#   - Frozen (Ractor.make_shareable): abstract_registry, view_context_registry,
+#     shareable_fallback
+#
+# The frozen registries start as empty shareable Hashes and are swapped
+# (via reassign_*) at prepare_for_ractors! / make_app_shareable! time with
+# the populated, frozen, shareable versions. The mutable registries are
+# appended at boot (main Ractor) and read at request time (worker Ractors).
+
+module RactorRailsShim
+  module Registry
+    @class_attributes = []
+    @mattr_defaults = {}
+    @class_attr_values = {}
+    @shareable_mattr_defaults = {}
+    @shareable_constants = []
+    @shareable_class_ivars = []
+    @abstract_registry = Ractor.make_shareable({})
+    @view_context_registry = Ractor.make_shareable({})
+    @shareable_fallback = Ractor.make_shareable({})
+
+    class << self
+      attr_reader :class_attributes, :mattr_defaults, :class_attr_values,
+                  :shareable_mattr_defaults, :shareable_constants,
+                  :shareable_class_ivars, :abstract_registry,
+                  :view_context_registry, :shareable_fallback
+
+      # Swap the frozen (shareable) registries. The value MUST already be
+      # frozen + Ractor.make_shareable. Each reassign_* updates the
+      # instance variable; the facade alias (defined in patches/core.rb)
+      # re-reads it on every access, so the alias tracks the new value
+      # without a const_set on the facade singleton.
+      def reassign_shareable_fallback(value)
+        @shareable_fallback = value
+      end
+
+      def reassign_shareable_mattr_defaults(value)
+        @shareable_mattr_defaults = value
+      end
+
+      def reassign_abstract_registry(value)
+        @abstract_registry = value
+      end
+
+      def reassign_view_context_registry(value)
+        @view_context_registry = value
+      end
+
+      # Test seam: reset all nine registries to their boot defaults. Used
+      # by specs that mutate the registries and need a clean slate.
+      def reset_all
+        @class_attributes = []
+        @mattr_defaults = {}
+        @class_attr_values = {}
+        @shareable_mattr_defaults = {}
+        @shareable_constants = []
+        @shareable_class_ivars = []
+        @abstract_registry = Ractor.make_shareable({})
+        @view_context_registry = Ractor.make_shareable({})
+        @shareable_fallback = Ractor.make_shareable({})
+      end
+    end
+  end
+end

data/lib/ractor_rails_shim/foundation/role_defaults.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# RoleDefaults — DRY mixin for the three shared default-proc patterns
+# used by every role object with a configure seam (Issue #44, POODR §8e).
+#
+# Every role with a `funnel` seam copies:
+#   @funnel || RactorRailsShim::Funnel.method(:swallow)
+# Every role with a `safe_const_get` seam copies:
+#   @safe_const_get || RactorRailsShim::ConstantShareabilizer.method(:safe_const_get)
+# Every role with a `reassign_shareable_const` seam copies:
+#   @reassign_shareable_const || RactorRailsShim.method(:_reassign_shareable_const)
+#
+# `RoleDefaults` centralises the three defaults; each role `extend`s it
+# and its `funnel` / `safe_const_get` / `reassign_shareable_const` reader
+# calls `default_funnel` etc. The boilerplate collapses to one definition.
+#
+# Usage in a role module:
+#
+#   module MyRole
+#     extend RoleDefaults
+#
+#     @funnel = nil
+#     @safe_const_get = nil
+#
+#     def self.configure(funnel: nil, safe_const_get: nil)
+#       @funnel = funnel
+#       @safe_const_get = safe_const_get
+#     end
+#
+#     def self.reset_configuration
+#       @funnel = nil
+#       @safe_const_get = nil
+#     end
+#
+#     def self.funnel
+#       @funnel || default_funnel
+#     end
+#
+#     def self.safe_const_get
+#       @safe_const_get || default_safe_const_get
+#     end
+#   end
+#
+module RactorRailsShim
+  module RoleDefaults
+    def default_funnel
+      RactorRailsShim::Funnel.method(:swallow)
+    end
+
+    def default_safe_const_get
+      RactorRailsShim::ConstantShareabilizer.method(:safe_const_get)
+    end
+
+    def default_reassign_shareable_const
+      RactorRailsShim.method(:_reassign_shareable_const)
+    end
+  end
+end

data/lib/ractor_rails_shim/foundation/run_mode.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# RunMode: the thread-mode vs Ractor-mode configuration decision.
+#
+# Extracted from the RactorRailsShim singleton (`core.rb`) per POODR: deciding
+# which mode the shim runs in is a *configuration* responsibility, distinct
+# from the install orchestration that consumes the decision. The decision
+# used to be a side effect buried inside `install` (reading `ENV["SERVER"]`
+# into `@thread_mode`), which made install non-deterministic based on ambient
+# ENV with no visible configuration surface. RunMode owns that decision so it
+# is independently specable and configurable:
+#
+#   RactorRailsShim::RunMode.thread = true        # explicit
+#   RactorRailsShim::RunMode.detect_from_env       # ENV-based (pure query)
+#   RactorRailsShim::RunMode.resolve!              # install-time: explicit,
+#                                                  # else fall back to ENV
+#   RactorRailsShim::RunMode.thread?               # the answer
+#   RactorRailsShim::RunMode.reset                 # test/teardown helper
+#
+# The RactorRailsShim facade keeps `thread_mode?` / `thread_mode=` delegates
+# so existing call sites (patches/class_attribute.rb, patches/active_support.rb,
+# specs that set `RactorRailsShim.thread_mode = true`) keep working unchanged.
+module RactorRailsShim
+  module RunMode
+    # SERVER values that select thread-server (Puma/Falcon/Thin/Webrick) mode
+    # instead of the default Ractor mode. Matched case-insensitively. Kept as a
+    # Regex to mirror the original `core.rb:189` predicate exactly.
+    THREAD_SERVER_RE = /puma|falcon|thin|webrick|thread/i.freeze
+
+    class << self
+      # The resolved mode: true for thread-server mode, false for Ractor mode.
+      # Defaults to false when never configured. After `resolve!` or an
+      # explicit `thread=`, this is sticky — ENV no longer affects it.
+      def thread?
+        return @thread if defined?(@thread)
+        false
+      end
+
+      # Explicitly set the mode. Once called, `resolve!` becomes a no-op:
+      # explicit configuration wins over ambient ENV. This mirrors the old
+      # `install` body's `unless defined?(@thread_mode)` guard, lifted into
+      # the object that owns the state.
+      def thread=(value)
+        @thread = !!value
+      end
+
+      # Pure query of the ambient ENV["SERVER"]. Returns true when the server
+      # name matches a known thread server (puma|falcon|thin|webrick|thread*),
+      # case-insensitively; false otherwise (including when SERVER is unset or
+      # empty). Has no side effects and does not mutate RunMode state — call
+      # `resolve!` to fold the ENV answer into the resolved mode.
+      def detect_from_env
+        server = ENV["SERVER"]
+        return false unless server
+        !!(server =~ THREAD_SERVER_RE)
+      end
+
+      # The install-time decision. If the mode has already been set explicitly
+      # (via `thread=`), keep it — explicit wins over ENV. Otherwise, detect
+      # from ENV and freeze that as the resolved mode. Idempotent: a second
+      # call is a no-op because the first call (or an explicit `thread=`)
+      # defined `@thread`.
+      def resolve!
+        return if defined?(@thread)
+        @thread = detect_from_env
+        @thread
+      end
+
+      # Reset to the unconfigured state. For specs and teardown; not part of
+      # the public install contract.
+      def reset
+        remove_instance_variable(:@thread) if defined?(@thread)
+      end
+    end
+  end
+end

data/lib/ractor_rails_shim/foundation/storage.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# Storage role (Issue #14, Step 14.1): a pluggable key-value store contract
+# (`[]`, `[]=`, `key?`, `delete`) with two implementations:
+#
+#   * `Storage::IES`        — delegates to ActiveSupport::IsolatedExecutionState.
+#   * `Storage::ThreadLocal` — the former `FallbackIES` body (a thread-local
+#     Hash). Used only when AS is absent.
+#
+# `RactorRailsShim.storage` is set once at load time: IES when AS is loaded,
+# ThreadLocal otherwise. The eval'd method bodies in the patch files route
+# through `RactorRailsShim.storage[...]` instead of the literal
+# `ActiveSupport::IsolatedExecutionState[...]`, so the shim no longer needs to
+# open the ActiveSupport namespace to alias the fallback onto it (Step 14.3
+# deletes that namespace patch).
+#
+# The contract is intentionally minimal: the patch sites only use `[]`, `[]=`,
+# `key?`, and (rarely) `delete`. `clear` is provided on ThreadLocal for
+# spec/parity with the former FallbackIES API but is not part of the
+# cross-implementation contract.
+
+module RactorRailsShim
+  module Storage
+    # Delegates to the real ActiveSupport::IsolatedExecutionState when AS is
+    # loaded. Methods are class methods on the module's singleton class so
+    # callers do `Storage::IES[key]`.
+    module IES
+      class << self
+        def [](key)
+          ActiveSupport::IsolatedExecutionState[key]
+        end
+
+        def []=(key, value)
+          ActiveSupport::IsolatedExecutionState[key] = value
+        end
+
+        def key?(key)
+          ActiveSupport::IsolatedExecutionState.key?(key)
+        end
+
+        def delete(key)
+          ActiveSupport::IsolatedExecutionState.delete(key)
+        end
+      end
+    end
+
+    # Thread-local fallback: the former `FallbackIES` body. A per-thread Hash
+    # stored under a well-known key on Thread.current. Provides `clear` for
+    # spec/parity (not part of the cross-implementation contract).
+    module ThreadLocal
+      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
+
+    # Select once at load: IES when AS is loaded, ThreadLocal otherwise.
+    @storage =
+      if defined?(::ActiveSupport::IsolatedExecutionState)
+        IES
+      else
+        ThreadLocal
+      end
+
+    class << self
+      # The active storage implementation (either `Storage::IES` or
+      # `Storage::ThreadLocal`). Exposed as `RactorRailsShim.storage` by the
+      # facade (defined in `patches.rb`).
+      attr_reader :storage
+    end
+  end
+
+  class << self
+    # The active storage implementation. Patch sites route through this so the
+    # shim doesn't open the ActiveSupport namespace to alias the fallback.
+    def storage
+      Storage.storage
+    end
+  end
+end