ractor-rails-shim 0.2.6 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a4b7ce968f90326f2b476d713b7fab6c524f8f7b111f60a2ae582d1e162de88
-  data.tar.gz: c144478be527ff98804db48add54d67edb4124514fba3670b970990ef09e36c0
+  metadata.gz: 6ebcbda319623aa7003caf170774074e19fdf2d6452ed086fbc5edbfec037fa5
+  data.tar.gz: 7ab60400652444ccbc5ca39ac403d387c156cc8a6178700f10c9d744db9c3fad
 SHA512:
-  metadata.gz: 55cc0fb00ebd523182cb66f8ae7a9f270bf33bcaaf928af79d291edf3eeb0248246f956e082200ab74563c7afceee8520336f53373ed9d54ff73f4db9ce05f40
-  data.tar.gz: b19280d1985a1e8b456a6a13750e277a49c5123998a4f7fab587518d3d6a717249d9490cfbe6d32751483d9c5e622373d861fbed9ce50d8daeabb09578b897e9
+  metadata.gz: 69433fe039a2e2bea0302e13117a0ba701b786eaaec6e2e636d1d4786d74428e11701db2c703bc6fdb10c698febb6d5bce646adba24011513802d76de237349f
+  data.tar.gz: 615e99053521f65e7aa013d8a5c23e97991bd8b3f8593a92c9c2cf57e2ab245796bde664731ac943fe6b52681a8416c4bddac9635a7c5be6b2c3cc6339ecbdd2

data/CHANGELOG.md

@@ -7,6 +7,163 @@ 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

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