ractor-rails-shim 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21002fee5a30f663904441d8c016c035564095bf456048a25917657e9adab5fc
-  data.tar.gz: dcb6764139de152ae7b958112503efc7951d59ae211c04ee268da6bf63a2be51
+  metadata.gz: c9a5a31eef9fc564a38af828fa80c55909878e502952358a129760441b36844b
+  data.tar.gz: ed5bee3ef13dd02d95ab06e806cebc2a1248da438e6f82133654419a85485c28
 SHA512:
-  metadata.gz: 28cf75ae0f4972142cee3965d5c68fd8b70c09b901dc60c186f178ac403fc7695c3f7e2e77e4591c9aa6aa0fc9c6d1ba5eafa8e3c64d5abad545b50159159d6c
-  data.tar.gz: b1bf30685c4b7082c5930a63693571e4d3affff2fa0b530fd355aaf5a57f5cf42280ff5a590f099705e8af573ae953d654ace88fbb813dc05e463379fa0c09c7
+  metadata.gz: c77e93d1676466dd59164e597f888837df387669a8579e0e3f5d2056fab47e4a9b7bcca7502993f932fdffc7e906b933a9724a71ab167bfb835680e083dba3d6
+  data.tar.gz: 5822e8b0c5cb9c9ab204b9b052cb1501a1ecb4bf9a3d8737881095771835d8be5b7441f5d5d665ef1bb6781d422240a0135bc56079f02e5d08823bb8a8142c46

data/CHANGELOG.md

@@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0]
+
+### Added — Rails feature support for worker Ractors
+- **`render json:` / `render xml:` / `render js:` in worker Ractors.**
+  ActionController::Renderers defines `_render_with_renderer_*` via
+  `define_method(&block)` at boot — the block is compiled in the main Ractor
+  and can't be called from a worker. Redefined all three as string-eval'd
+  `def`s (no captured binding) callable from any Ractor.
+  (`_install_json_renderer_patch`, `patches/action_controller.rb`)
+
+- **ActionMailer `deliver_now` from a worker Ractor.** The full build +
+  ERB render + deliver path works in a worker Ractor. Patches the `mail`
+  gem (raw `@@cvar`s routed through per-Ractor IES; `Mail::Configuration`
+  per-worker; `Mail::Parsers::*Parser` + `Mail::Utilities` module ivars
+  captured into a shareable constant with string-eval `def` readers;
+  `Mail::TestMailer.deliveries` per-Ractor; `Mail::PartsList` /
+  `AttachmentsList` `DelegateClass` delegating methods redefined as
+  shareable `def`s). Patches `ActionMailer::Base` (`mailer_name` callers
+  reimplemented via string-eval; `PROTECTED_IVARS` made shareable; `config`
+  falls back to empty `OrderedOptions` when `class_attribute` resolves nil;
+  `local_prefixes` overridden for mailers). SMTP delivery also viable
+  (`Mail::SMTP::DEFAULTS` made shareable). (`patches/mail.rb`)
+
+- **ActiveStorage `has_one_attached` in a worker Ractor.** Blob creation,
+  file upload, attachment persistence, and cross-worker read-back all work.
+  16 patched layers:
+  - `has_one_attached` / `has_many_attached` scope lambda built with a
+    shareable `self` so `User.reflections` is Ractor-shareable.
+  - `Blob.build_after_unfurling` / `compute_checksum_in_chunks` redefined
+    without `tap` blocks.
+  - `Blob#service_name` falls back to `self.class.service&.name`.
+  - `Blob.type_for_attribute(:metadata)` / `attribute_types` / per-worker
+    `_default_attributes` force `Type::Serialized` with
+    `IndifferentCoder(JSON)` for `:metadata`.
+  - `generated_attribute_methods` modules captured in
+    `SHAREABLE_GEN_ATTR_METHODS` at prepare time; workers read via per-Ractor
+    IES instead of creating an empty Module.
+  - `ActiveRecord::Store#store_accessor` redefined as string-eval `def`s;
+    `store_accessor_for` coder resolution block-free.
+  - `ThroughReflection#source_reflection_name` respects `options[:source]`.
+  - `ThroughReflection#check_validity!` uses per-worker cache (was writing
+    `@validated` on frozen reflection → FrozenError).
+  - `full_table_name_prefix` / `full_table_name_suffix` reimplemented
+    without un-shareable `module_parents.detect { }` blocks.
+  - `attribute_names` aliased to `_rrs_orig_attribute_names` (was `super`
+    with no superclass method); `define_attribute_methods` calls original
+    in main (was no-op everywhere).
+  - `SecureRandom::BASE36_ALPHABET` / `BASE58_ALPHABET` deep-frozen at
+    `prepare_for_ractors!` time.
+  - `ActiveStorage.table_name_prefix` / `table_name_suffix` redefined as
+    shareable string-eval `def`s; `_seed_active_storage_prefix!` seeds
+    constants and resets `Blob`/`Attachment` `table_name` in main.
+  - `Marcel::MimeType` / `Marcel::Magic` block-based methods redefined as
+    string-eval `def`s; lookup tables frozen.
+  - `ActiveStorage::Service::Registry#fetch` works via `class_attribute`
+    fallback.
+  - `Devise.mailer` `@@mailer_ref` cvar captured as shareable constant;
+    workers read the captured copy.
+  - Callback `if:` / `unless:` Symbol conditions captured and checked via
+    `condition_allows?` in SymbolicTransport.
+  (`patches/active_storage.rb`, `patches/active_record_store.rb`,
+  `patches/marcel.rb`, `patches/active_model_attribute.rb`,
+  `patches/activerecord.rb`, `patches/activerecord_reflection.rb`,
+  `patches/devise.rb`, `callbacks/symbolic_transport.rb`,
+  `roles/callback_capture.rb`, `roles/shareability_traversal.rb`)
+
+- **`FEATURES.md` — feature support matrix.** Documents every supported /
+  unsupported / unverified feature for worker Ractor mode, with known
+  limitations (around callbacks, sanitize/Nokogiri, ActiveJob
+  `perform_later`, block `after_save` workaround, GlobalID
+  `after_create_commit` workaround).
+
+### Known limitations
+- `around_action` / `:around` callbacks — not transported (must wrap yield).
+- `sanitize` / `simple_format` (Nokogiri) — ractor-unsafe C extension.
+- ActiveJob `perform_later` / `deliver_later` — `queue_adapter`
+  `class_attribute` resolves nil in workers; `GlobalID.app` class ivar not
+  captured by the shim (nil in workers). **TODO #5**.
+- `has_one_attached` block `after_save` callback — lambda can't cross
+  Ractor boundary. Probe uses `blob.unfurl` + `insert!` workaround.
+- `ActiveStorage::Attachment` `after_create_commit` callbacks — enqueue
+  ActiveJobs via GlobalID (`@app` nil in workers). Probe uses `insert!`.
+
 ## [0.3.0]
 
 ### Changed — breaking (public API)

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/callbacks/dependent_association_transport.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Callbacks::DependentAssociationTransport — replays a model's `dependent:`
+# association cascades on the `:destroy` kind. This is the reference transport
+# for a callback that is a LAMBDA (the `dependent:` option registers an
+# unshareable `before_destroy` lambda) but whose *effect* reduces to a
+# shareable, declarative spec: (class_name => [{name:, type:, macro:}]).
+#
+# On `:destroy`, for each captured dependent association the transport calls
+# `record.association(name).handle_dependency` — the exact method the original
+# lambda invoked — so `:destroy` / `:delete` / `:nullify` / `:restrict_*` all
+# dispatch correctly (that dispatch lives in AR's handle_dependency).
+#
+# Source shape (frozen into SHAREABLE_DEPENDENT_ASSOCIATIONS):
+#   { class_name(String) => [ {name: Symbol, type: Symbol, macro: Symbol}, … ] }
+#
+# Keyed by class *name* (not object_id) because `dependent:` replay looks up the
+# record's own class, not its ancestors (a class only cascades the associations
+# it itself declared).
+
+module RactorRailsShim
+  module Callbacks
+    class DependentAssociationTransport
+      # source: a Hash { class_name => [entry, …] } as described above, OR a
+      # callable returning that Hash (resolves the shareable constant lazily at
+      # replay time in a worker).
+      def initialize(source:)
+        @source = source
+      end
+
+      def source
+        s = @source
+        return s.call if s.respond_to?(:call)
+        return ::RactorRailsShim.const_get(s) if s.is_a?(::Symbol)
+        s
+      rescue StandardError
+        nil
+      end
+
+      # This transport ONLY owns the `:destroy` kind. (The symbolic transport
+      # also applies to :destroy for app before_destroy methods; both run.)
+      def applies_to?(kind)
+        kind == :destroy
+      end
+
+      # Re-drive every dependent association the record's class declared,
+      # BEFORE the record itself is deleted (matching the before_destroy order).
+      def before(context, kind)
+        return unless kind == :destroy
+        table = source
+        entries = table && table[class_name_of(context)]
+        return unless entries
+        entries.each do |entry|
+          assoc = association_of(context, entry[:name])
+          assoc.handle_dependency if assoc && assoc.respond_to?(:handle_dependency)
+        end
+      end
+
+      # Dependent cascades are a before_destroy concern; nothing runs after.
+      def after(_context, _kind)
+        nil
+      end
+
+      private
+
+      def class_name_of(context)
+        klass = context.class
+        klass.name if klass.respond_to?(:name)
+      rescue StandardError
+        nil
+      end
+
+      def association_of(context, name)
+        context.association(name) if context.respond_to?(:association)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/ractor_rails_shim/callbacks/registry.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Callbacks::Registry — the coordinator that dispatches callback replay across
+# an open set of {Callbacks::Transport} objects (POODR §3 duck-typing, §5
+# message-based design, Open/Closed: add a callback *kind* by registering a new
+# transport, not by editing a `case kind` branch).
+#
+# The Registry owns the single `yield` of the real callback-chain body. Each
+# applicable transport runs its `before` work, then the block runs once, then
+# each runs its `after` work. This lets two transports legitimately share a kind
+# (e.g. on `:destroy` both the symbolic `before_destroy` filters AND the
+# `dependent:` cascade run) without any transport owning the block.
+#
+# A transport duck-types to:
+#   applies_to?(kind)   -> bool
+#   before(context, kind) -> runs before-filter work for that chain kind (no-op ok)
+#   after(context, kind)  -> runs after-filter work for that chain kind (no-op ok)
+#   install            -> hook into the framework to begin capturing (optional)
+#   capture            -> finalize the shareable snapshot (optional)
+#
+# Both `install` and `capture` are optional; the Registry forwards them and
+# ignores any transport that does not respond.
+
+module RactorRailsShim
+  module Callbacks
+    class Registry
+      # transports: an Enumerable of transport objects (duck-typed). Defaults
+      # to empty so callers can `register` incrementally.
+      def initialize(transports = [])
+        @transports = transports.is_a?(Enumerable) ? transports.to_a : Array(transports)
+      end
+
+      # Register one transport. Returns self for chaining.
+      def register(transport)
+        @transports << transport
+        self
+      end
+
+      # The subset of transports that apply to `kind`. Public so tests (and a
+      # future "is anything replayable for this kind?" check) can introspect.
+      def applicable(kind)
+        @transports.select { |t| t.applies_to?(kind) }
+      end
+
+      # Replay the empty callback chain for `context` and `kind`. Runs every
+      # applicable transport's before-work, yields the block ONCE, then runs
+      # every applicable transport's after-work. Returns the block's result.
+      # If nothing applies, just yields (matching the original empty-chain path).
+      def replay(context, kind, &block)
+        applicable = applicable(kind)
+        return yield if applicable.empty?
+        applicable.each { |t| t.before(context, kind) }
+        result = yield
+        applicable.each { |t| t.after(context, kind) }
+        result
+      end
+
+      # Forward the optional framework-hooking phase to every transport that
+      # responds. Idempotent install is each transport's own concern.
+      def install
+        @transports.each { |t| t.install if t.respond_to?(:install) }
+      end
+
+      # Forward the optional finalize-the-snapshot phase to every transport
+      # that responds. Called from the main Ractor at prepare time.
+      def capture
+        @transports.each { |t| t.capture if t.respond_to?(:capture) }
+      end
+    end
+  end
+end

data/lib/ractor_rails_shim/callbacks/symbolic_transport.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "set"
+
+# Callbacks::SymbolicTransport — replays captured SYMBOLIC callback filters
+# (method-name filters such as `before_save :normalize_title`) for ANY callback
+# kind. This is the generic half of "a solution for any callback": a callback
+# declared with a Symbol is shareable (the Symbol crosses the Ractor boundary),
+# so we capture it at declaration time and re-invoke the method in the worker.
+#
+# Generalizes the controller-only `:process_action` replay to every kind
+# (`:save`, `:create`, `:update`, `:destroy`, `:validation`, `:commit`, …) and
+# to both controllers and ActiveRecord models.
+#
+# Source shape (frozen into SHAREABLE_DECLARED_CALLBACKS by CallbackCapture):
+#   { class_object_id => [ {chain_kind:, phase:, filter:, only:, except:}, … ] }
+# where `chain_kind` is the ActiveSupport::Callbacks chain name (e.g. :save),
+# `phase` is :before / :after, and `only`/`except` are nil or frozen Arrays of
+# action-name Symbols. All values are natively shareable.
+#
+# The transport is duck-typed around `context`:
+#   - context.class.ancestors -> Enumerable of class-like objects with object_id
+#   - context.class.object_id  -> the key the source is indexed by
+#   - context.action_name      -> Symbol or nil (only meaningful for controllers)
+#   - context.respond_to?(filter, true) + context.public_send(filter)
+#
+# `:around` symbolic filters are NOT transported (they must wrap the yield, and
+# the Registry owns the single yield). Rails `:around` callbacks are almost
+# always lambdas anyway; documented as a known limitation in ARCHITECTURE.md §5c.
+
+module RactorRailsShim
+  module Callbacks
+    class SymbolicTransport
+      # The callback chain kinds this transport owns by default. Controllers
+      # use `:process_action`; models use :save/:create/:update/:destroy and
+      # their sub-kinds (:validation, :commit, :rollback). Filter methods defined
+      # via `define_method(&block)` with an un-shareable Proc (e.g. AR's autosave
+      # association callbacks) are rescued and skipped so app `def` callbacks
+      # still run.
+      DEFAULT_KINDS = [
+        :process_action,
+        :save, :create, :update, :destroy,
+        :validation, :commit, :rollback
+      ].freeze
+
+      # source: a Hash { class_object_id => [entry, …] } as described above, OR a
+      # callable returning that Hash, OR a Symbol naming the shareable constant
+      # to resolve via const_get (so a worker reads the frozen constant after
+      # prepare, not a stale snapshot).
+      # kinds: the set of chain kinds this transport owns (default
+      # DEFAULT_KINDS, which includes model lifecycle kinds). Unshareable-Proc
+      # filters are rescued and skipped automatically.
+      def initialize(source:, kinds: DEFAULT_KINDS)
+        @source = source
+        @kinds = kinds.is_a?(::Set) ? kinds : ::Set.new(kinds.to_a)
+      end
+
+      def source
+        s = @source
+        return s.call if s.respond_to?(:call)
+        return ::RactorRailsShim.const_get(s) if s.is_a?(::Symbol)
+        s
+      rescue StandardError
+        nil
+      end
+
+      # Whether this transport owns `kind`. Configured by `kinds:` so the
+      # registry can compose multiple symbolic transports for different kind
+      # sets without editing this class (Open/Closed).
+      def applies_to?(kind)
+        @kinds.include?(kind)
+      end
+
+      # Run the matching :before filters for `kind`, ancestor-first, respecting
+      # only/except. `respond_to?` guards each send so a stale capture never
+      # raises NoMethodError (matches the original controller replay behavior).
+      #
+      # A filter defined via `define_method(&block)` with an un-shareable Proc
+      # raises "defined with an un-shareable Proc in a different Ractor" when
+      # `send`-ed in a worker. ActiveRecord generates such methods for autosave
+      # associations (e.g. `autosave_associated_records_for_*`). We SKIP those
+      # filters and continue the chain so app-defined `def` callbacks still run.
+      def before(context, kind)
+        each_applicable_filter(context, kind, :before) do |entry|
+          next unless condition_allows?(context, entry)
+          context.send(entry[:filter]) if context.respond_to?(entry[:filter], true)
+        rescue RuntimeError => e
+          raise e unless unshareable_proc_error?(e)
+          # Skip the unshareable-Proc filter; the chain continues.
+        end
+      end
+
+      # Run the matching :after filters for `kind`, ancestor-first.
+      def after(context, kind)
+        each_applicable_filter(context, kind, :after) do |entry|
+          next unless condition_allows?(context, entry)
+          context.send(entry[:filter]) if context.respond_to?(entry[:filter], true)
+        rescue RuntimeError => e
+          raise e unless unshareable_proc_error?(e)
+        end
+      end
+
+      private
+
+      # Walk the context's class hierarchy, collecting every entry whose
+      # chain_kind + phase match, then yield them in Rails' accumulation order:
+      # superclass filters BEFORE subclass filters, declaration order preserved
+      # within each class. `only`/`except` gate each entry against the context's
+      # `action_name` when present.
+      def each_applicable_filter(context, kind, phase)
+        action = action_name_of(context)
+        ancestors = ancestors_of(context)
+        # ancestors is instance-class-first; we want superclass-first so
+        # superclass filters run before subclass filters (Rails order), but
+        # declaration order is preserved within each class (no reversal).
+        collected = []
+        table = source
+        return unless table # no captured table yet → nothing to replay
+        ancestors.reverse_each do |klass|
+          entries = table[class_id_of(klass)]
+          next unless entries
+          entries.each do |entry|
+            next unless entry[:chain_kind] == kind
+            next unless entry[:phase] == phase
+            next unless action_constraint_allows?(entry, action)
+            collected << entry
+          end
+        end
+        collected.each { |e| yield e }
+      end
+
+      def action_name_of(context)
+        action = context.action_name if context.respond_to?(:action_name)
+        action = action.to_sym if action
+        action
+      rescue StandardError
+        nil
+      end
+
+      def ancestors_of(context)
+        klass = context.class
+        klass.respond_to?(:ancestors) ? klass.ancestors : [klass]
+      end
+
+      def class_id_of(klass)
+        klass.object_id
+      end
+
+      # Whether an exception is the "un-shareable Proc in a different Ractor"
+      # RuntimeError raised by `send`-ing a `define_method(&block)` method
+      # cross-Ractor. We match on a substring so the check survives minor
+      # wording changes in the Ruby error message.
+      def unshareable_proc_error?(error)
+        error.message.include?("un-shareable Proc")
+      end
+
+      # only: nil (always), [:a, :b] (only those actions); except: nil (never
+      # skip), [:a] (skip those). nil action means "no action context" — only
+      # runs if the filter has no :only constraint (i.e. :only is nil).
+      def action_constraint_allows?(entry, action)
+        only = entry[:only]
+        except = entry[:except]
+        in_only = only.nil? || (action && only.include?(action))
+        not_except = except.nil? || !(action && except.include?(action))
+        in_only && not_except
+      end
+
+      # Check Symbol if:/unless: conditions on the callback entry against the
+      # context. `if_cond` / `unless_cond` are Symbol method names (or nil).
+      # The method is called on the context; truthy = run, falsy = skip.
+      # Non-Symbol conditions (lambdas/Procs) are NOT captured (they're
+      # unshareable), so nil means "no condition" (always allow).
+      def condition_allows?(context, entry)
+        if entry[:if_cond]
+          return false unless context.respond_to?(entry[:if_cond], true) &&
+                              context.send(entry[:if_cond])
+        end
+        if entry[:unless_cond]
+          return false if context.respond_to?(entry[:unless_cond], true) &&
+                           context.send(entry[:unless_cond])
+        end
+        true
+      rescue StandardError
+        # If the condition method raises, skip the callback (safer than
+        # running it unconditionally).
+        false
+      end
+    end
+  end
+end