ractor-rails-shim 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9a5a31eef9fc564a38af828fa80c55909878e502952358a129760441b36844b
-  data.tar.gz: ed5bee3ef13dd02d95ab06e806cebc2a1248da438e6f82133654419a85485c28
+  metadata.gz: abdcca0b7262caf6686c80535a98635edcb4a6f02e373d1ab1cedde7d9ee8867
+  data.tar.gz: 021d39390668e696131e221d1a767a763ebc0765fa37ff3b5a4dbd082609b010
 SHA512:
-  metadata.gz: c77e93d1676466dd59164e597f888837df387669a8579e0e3f5d2056fab47e4a9b7bcca7502993f932fdffc7e906b933a9724a71ab167bfb835680e083dba3d6
-  data.tar.gz: 5822e8b0c5cb9c9ab204b9b052cb1501a1ecb4bf9a3d8737881095771835d8be5b7441f5d5d665ef1bb6781d422240a0135bc56079f02e5d08823bb8a8142c46
+  metadata.gz: 977596297e62a5743b33c7afcfdec8b3cb4f3be66aca0e477f7de4acc03f3213cfe04138bc99dbfb5bbe4982e8852cd47d145fce7e0536f60d9b5216cf7e4709
+  data.tar.gz: 6a46bc0e33bca9f70752effbfb6c5ba90e85b71cff16259b828787a1a9d539c1a93bbd32f491cbb681f7246527ffcb6065ba69cb2ae3ba7f92e9ef95c3c9359f

data/CHANGELOG.md

@@ -7,6 +7,651 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.1] — 2026-10-25
+
+### Release housekeeping
+
+- Version bump only. No functional changes.
+
+## [0.5.0] — 2026-10-24
+
+### Performance — read-path hot-loop optimization (measured)
+
+Four changes targeting the per-request class-attribute/config read path,
+benchmarked after each against the test app under kino `:ractor` (-w5 -t1,
+Ruby 4.0.7, ab c=64):
+
+- **Single-probe IES hit** (`StorageStrategy::Ractor` and all ~53 inline
+  eval'd readers): the non-nil IES hit no longer pays a second
+  `storage.key?` probe — the stored-nil disambiguation moved to the nil
+  path. Semantics identical (a stored nil is still a hit). Micro-bench
+  exact-key reader 2.51 → 3.52 Mops/s.
+- **Worker IES prefill** (`WorkerApp#setup_once!`): each worker copies the
+  frozen shareable fallback table's non-nil slots into its own IES on
+  first request, so every later read of fallback-backed config is a
+  single first-tier hit. Per-ractor overrides are preserved (key? guard).
+- **Boot-time GC.compact** (`prepare_for_ractors!`): one compaction in
+  main after the shareabilization passes, before workers spawn.
+  Explicitly NOT `GC.auto_compact` (which hangs kino :ractor under load).
+  Opt-outs: `RRAILS_SHIM_DISABLE_BOOT_COMPACT=1` / `RUBY_GC_DISABLE_COMPACTION=1`.
+- New `bench/accessor_read_bench.rb` micro-benchmark (raw ivar floor vs
+  each lookup shape).
+- **Compiled callback chains** (`SymbolicTransport` + `Registry`): chains
+  compile once per (class, kind) into frozen phase arrays — one ancestor
+  walk instead of three per replay, no per-replay `const_get` or
+  transport select. Micro-bench: 0.07 → 0.21 Mops/s (3×). E2E POST /posts
+  3,000 → 3,445 rps on top of the other changes; `/up` 14,991 → 16,031.
+
+End-to-end (req/s, baseline → full stack; two independent full-stack runs
+agreed within noise): `/up` 13,986 → ~15,400 (+7-13%), `/posts_plain`
+4,245 → 4,743-4,900 (+12-15%), `POST /posts` 2,442 → 2,728-3,000
+(+12-23%), `/posts` (Kaminari, DB-bound) 527 → 548-574 (+4-9%). Memory
+flat (~270 MB cold). All 832 unit specs + strategy_proc + integration
+spec green.
+
+### Added — multi-database (`connects_to` / `connected_to`) in worker Ractors
+
+Test-app row 81 now runs a real second database, which exposed three gaps in
+the worker connection setup:
+
+- `init_worker_ar_connections!` established EVERY configured database on the
+  `:default` shard, so in a multi-database app the LAST config won — workers
+  queried the secondary database and raised `PG::UndefinedTable` for every
+  primary table. The config named `primary` (Rails' convention) now owns the
+  default shard; single-database apps fall back to the first entry.
+- Each named database is registered for the writing AND the reading role;
+  `connected_to(role: :reading)` otherwise raised "calling `connected_to` is
+  not allowed when there is no connection defined for that role".
+- New `_capture_ar_connection_classes!` (main, prepare time) records every
+  model that owns a pool via `connects_to` (Solid Cache/Queue/Cable records,
+  app multi-database models) together with the db config main resolved.
+  Workers re-establish those pools from the snapshot under the model's own
+  `connection_specification_name` — a lazily autoloaded class re-resolved
+  `connects_to` to the PRIMARY config (observed: `AuditEntry` queried the
+  primary database and its table was "missing").
+
+Evidence: test app `/multi_db_probe` in a worker — secondary write + re-read,
+a primary read in the same request, and
+`SecondaryRecord.connected_to(role: :reading)`. Suite: 830 runs, 0 failures.
+
+### Added — turbo-rails worker support (test-app rows 105 + 121)
+
+Adopting turbo-rails and exercising ActiveStorage direct uploads in worker
+Ractors surfaced five framework-level walls, all fixed here:
+
+- `patches/thread_mattr.rb` (new, install-time): `Module#thread_mattr_reader/
+  writer` generate methods that memoize their IES key in a class/module ivar
+  (`@__thread_mattr_#{sym} ||=`) — a write that raises IsolationError in
+  workers. turbo-rails' `Turbo.current_request_id` (around_action on EVERY
+  request) and `ActiveRecord::Base.suppressed_turbo_broadcasts` hit this, so
+  every worker request died with a 500. The patched macros emit the
+  deterministic key without the ivar memo (same per-class isolation).
+- `patches/turbo.rb` (new, prepare-time): re-emits turbo's
+  `_render_with_renderer_turbo_stream` renderer as a string-eval'd `def`
+  (upstream `define_method`s a main-compiled Proc), and routes PROC layouts
+  (`Turbo::Frames::FrameRequest`'s conditional frame layout — re-emitted per
+  controller by the Layouts `inherited` hook) through a frozen
+  `PROC_LAYOUT_PROCS` registry read by a real `def _layout_from_proc`
+  (`instance_exec` preserves the define_method self-rebinding contract).
+- `patches/secure_token.rb` (new, install-time): `has_secure_token` registers
+  a BLOCK callback — skipped in workers, so worker-created rows had NULL
+  tokens (`ActiveStorage::Blob#key` → direct uploads died with
+  PG::NotNullViolation). The macro wrapper appends an equivalent Symbol
+  callback (and re-applies it to models loaded before the patch, e.g.
+  ActiveStorage::Blob).
+- `SymbolicTransport::DEFAULT_KINDS` now includes `:initialize` (Rails 8.1's
+  `generate_secure_token_on` default) — declared symbolic after_initialize
+  filters replay in workers.
+- `patches/active_storage.rb`: prebuilds every configured service +
+  warms each service's memoized `url_helpers` in main (DiskService#url wrote
+  to a frozen instance), registers the blob `service_name` default
+  symbolically (seeded `ACTIVE_STORAGE_DEFAULT_SERVICE`), injects that default
+  in `create_before_direct_upload!` (the endpoint passes an explicit nil),
+  and re-registers `ActiveStorage::SetCurrent` as a Symbol before_action
+  (the upstream block never replays → "Missing host to link to!").
+- `patches/active_controller.rb`-adjacent constants:
+  `ActionController::Parameters::EMPTY_ARRAY/EMPTY_HASH` registered shareable.
+
+Evidence: test app rows 105 (turbo stream responses, `.turbo_stream.erb`
+templates, model broadcast enqueued from a worker + performed by `bin/jobs`
+with a solid_cable message) and 121 (rich_text_area; full direct-upload
+endpoint cycle: POST → signed id/URL → disk PUT → blob redirect → service
+URL bytes). Embed parsing remains the documented Nokogiri wall (row 50).
+
+### Fixed — worker-side `:memory_store` / `:null_store` (`Rails.cache` raised FrozenError on the first call)
+
+`Rails.cache` is captured into `CLASS_ATTRIBUTES`. `FallbackBuilder` therefore
+deep-froze the store at prepare time.
+
+- `MemoryStore` refreshes LRU order with `@data.delete` / `@data[key] =` on
+  every read.
+- `NullStore` memoizes `@local_cache_key` on the instance.
+
+Both raised `FrozenError` on the first cache call in every Ractor. The failed
+`make_shareable` also froze the live main-Ractor store, so main broke too.
+Solid Cache and FileStore were unaffected: they hold no mutable hot-path state.
+
+- `roles/per_ractor_cache.rb` (new): process-local stores are swapped for a
+  same-class shareable proxy. `klass.allocate` plus a singleton delegator keeps
+  `class` and `is_a?` exact. The proxy holds only a shareable spec (class name
+  plus option values that survive `Ractor.make_shareable`). Every store method
+  delegates to a `Ractor.current`-memoized instance, so each Ractor gets its own
+  `MemoryStore` — the same shape as forked processes. The main Ractor keeps the
+  original instance and its boot-warmed entries. `Rails.cache` and
+  `ActionController::Base.config.cache_store` are re-pointed at the proxy from
+  both `prepare_for_ractors!` and `make_app_shareable!`.
+- `patches/active_support.rb`: `SerializerWithFallback::SERIALIZERS` added to
+  `SHAREABLE_CONSTANTS`. Worker-side store construction reads it through
+  `Store#initialize`. New `_install_cache_store_cattr_patch` re-routes
+  `Store.logger` / `raise_on_invalid_cache_expiration_time` through
+  `mattr_accessor` when `active_support/cache` loaded before the shim. Workers
+  cannot read `@@logger` at all.
+- `patches/rails_module.rb`: the worker `Rails.cache` reader returns the proxy
+  constant first, then the shareable fallback.
+- Redis/MemCache stores are not wrapped. Their connection config is not
+  reconstructible from `store.options`. A boot warning tells the operator to
+  use `:solid_cache_store` or `:file_store`.
+- Spec: `spec/per_ractor_cache_spec.rb` (7 cases: classification, same-class
+  shareable proxy, main keeps the original, worker write/read/fetch, per-Ractor
+  isolation, NullStore, FileStore unwrapped).
+
+### Fixed — worker-side `serialize :arguments, coder: JSON` (Solid Queue enqueue from a worker, row 110)
+
+Four coordinated fixes, all proven by the test app's `:ractor` suite plus an
+end-to-end kino + `bin/jobs` dispatcher run (worker enqueues; the separate
+dispatcher performs):
+
+- `patches/solid_queue.rb` (new): prewarms `SolidQueue::Batch.migrated?`
+  (a lazily-memoized boolean class ivar on a frozen engine-model class —
+  the first worker enqueue died on the `||=` write) and re-registers the
+  execution models' `before_create -> { assume_attributes_from_job }`
+  BLOCK callback symbolically (`before_create :assume_attributes_from_job`
+  via a string-eval'd redefinition of the `JobAttributes` macro). Without
+  the latter, SolidQueue's `ScheduledExecution` INSERT died with
+  PG::NotNullViolation (null `queue_name`) because SymbolicTransport
+  fail-safe skips block filters. Each execution model's current assumable
+  list is re-applied (ReadyExecution none/default, ScheduledExecution
+  `:scheduled_at`, BlockedExecution `:concurrency_key`).
+- `FallbackBuilder.try_make_shareable` no longer blanket-skips
+  `__class_attr__queue_adapter`: stateless DB-write adapters (SolidQueueAdapter)
+  freeze into the worker fallback so workers enqueue through the REAL
+  adapter; unshareable ones (AsyncAdapter's live scheduler) still fall back
+  to the declared default.
+- `_share_ar_pending_attribute_modifications!` gains a binding-locals
+  retry pass + `SerializedTypeDecorator` (callables.rb): decoration Procs
+  whose captured locals are unfrozen value objects (e.g. the `serialize`
+  macro's `ActiveRecord::Coders::JSON` instance) now freeze those locals in
+  place and retry; serialization.rb-sourced decorations that can never be
+  shared (`coder ||=` reassignment taints the proc) are reconstructed as a
+  shareable callable that rebuilds `Type::Serialized` per apply. WITHOUT
+  this, workers rebuilt the `arguments` attribute as a plain Text type and
+  stored Ruby hash-inspect instead of JSON (the dispatcher then died with
+  JSON::ParserError). SCOPE GUARD: only value-object coders
+  (ActiveRecord::Coders::* instances) are reconstructed — coder CLASSES
+  (ActionText::Content, whose load path needs Nokogiri — the permanent
+  worker wall) keep the pre-fix no-op behavior, preserving row 120's
+  raw-HTML round-trip.
+- `JsonCoderFreezer` (in patches/active_job.rb): freezes the
+  `JSONGemCoderEncoder::CODER` constant's value in main at prepare time so
+  the worker-side encode path (called by `ActiveRecord::Coders::JSON#dump`
+  through `Type::Serialized#serialize`) can read the constant legally.
+- `prepare_for_ractors!` pipeline gains two steps (wired through
+  `AppShareabilizer`'s configure seam): `prewarm_solid_queue` and
+  `freeze_json_coder`.
+
+### Added — worker-side `around_action` / `:around` callback replay (wrap-style)
+
+Symbolic method-name `:around` filters (`around_action :method`,
+`around_save :method`, …) now replay in worker Ractors. `SymbolicTransport`
+gains `around(context, kind, inner)` and `Registry#replay` builds a wrap
+chain around the single yield. Nesting is pinned against the real
+ActiveSupport compiled chain: first-declared `:around` filter outermost, the
+after-half runs inside the innermost `yield`, a filter that never yields
+suppresses the block and the after-half, and the chain evaluates to the
+block's result (a yielding filter's own return value is discarded; a
+non-yielding one evaluates to nil). Lambda/Proc around filters remain
+fail-safe skipped (un-shareable Procs — same policy as every other Proc
+filter). Specs: `spec/callbacks/around_transport_spec.rb`. This resolves the
+test-app TODO #90 decision (`around_action`) in favor of shim support.
+
+## [0.4.2]
+
+### Fixed — worker time-zone creation dies on `TZInfo::DataSource`'s class variables
+
+Surfaced by the same durations probe (the layer under the
+`ActiveSupport::TimeZone.[]` fix): every `ActiveSupport::TimeZone`
+creation resolves its TZInfo data through `TZInfo::DataSource.get`, which
+memoizes into the class variables `@@instance` / `@@default_mutex`. Ruby
+4.0 forbids ANY class-variable access from non-main Ractors
+(`Ractor::IsolationError: can not access class variables from non-main
+Ractors`).
+
+- `get` is now Ractor-aware: main keeps the upstream body verbatim
+  (class-variable memoize + mutex); workers get a per-Ractor DataSource
+  from IsolatedExecutionState built by the upstream private
+  `create_default_data_source` (same ruby-data/zoneinfo choice; per-
+  instance lookup caches make per-Ractor caching semantically
+  equivalent). The upstream `set` (manual source selection) stays
+  main-only.
+
+### Fixed — worker `Time.zone` resolution dies on `TimeZone.[]`'s Concurrent::Map class ivar
+
+Surfaced by the test app's durations probe (row 131: `Time.zone` /
+`Time.use_zone` from a worker).
+
+- `Time.zone` (and `in_time_zone` / `use_zone`) resolves zones through
+  `ActiveSupport::TimeZone.[]`, whose String branch memoizes into the class
+  ivar `@lazy_zones_map` — a `Concurrent::Map` set at load time. Both
+  halves are forbidden in workers: reading the unshareable Concurrent::Map
+  class ivar raises `Ractor::IsolationError` (can not get unshareable
+  values from instance variables of classes/modules), and a worker-side
+  memoize would try to set it.
+- The patched `[]` keeps the upstream body verbatim on main; workers use a
+  per-Ractor Hash cache from IsolatedExecutionState. Zone instances are
+  plain data and TZInfo lookups are worker-safe, so worker-local caches are
+  semantically equivalent. The numeric-offset branch (`all.find`) stays
+  main-only (`all` also reads class ivars).
+
+### Fixed — worker-side streaming (`ActionController::Live`) hangs / dies
+
+Surfaced by the test app's blob proxy dispatch (row 127:
+`GET /rails/active_storage/blobs/proxy/:signed_id/:filename` in a worker).
+
+- The Active Storage blob proxy controller includes `ActionController::Live`,
+  which processes the action on a pool thread: a lazy class-method reader
+  sets a class ivar (`@live_thread_pool_executor ||=
+  Concurrent::CachedThreadPool.new` — Ruby 4.0 forbids class-ivar writes
+  from non-main Ractors, `Ractor::IsolationError`), and `Live#process` then
+  blocks on `await_commit` until the spawned thread commits. Even with a
+  worker-local pool, the thread hop deadlocks in practice: any exception
+  before `commit!` kills the pooled thread (`abort_on_exception = true`)
+  and the request hangs forever.
+- The patch runs the streaming action INLINE in worker Ractors:
+  `new_controller_thread` yields on the request thread (main keeps the
+  upstream pool-thread behavior verbatim). The bytes still stream through
+  the Rack response body; only true streaming concurrency (early header
+  flush) is lost worker-side, which is documented in the row note.
+
+### Fixed — worker `Dependencies.interlock` read dies on the unshareable class ivar
+
+Surfaced by the same blob proxy dispatch (the next frame after the
+streaming fix): `ActionController::Live#process` runs the action inside
+`ActiveSupport::Dependencies.interlock.running { ... }`, and upstream sets
+the `interlock` class ivar at load time to an Interlock wrapping an
+unshareable `Concurrency::ShareLock` — reading it from a worker is a
+`Ractor::IsolationError` (can not get unshareable values from instance
+variables of classes/modules). Regular worker requests don't hit it: the
+shim's production stack drops the `ActionDispatch::Executor` middleware,
+the only other interlock consumer.
+
+- The reader is replaced with a Ractor-aware method: main returns the
+  upstream class ivar (100% upstream semantics); workers get a per-Ractor
+  Interlock from IsolatedExecutionState. Workers never reload (the graph
+  is frozen), so the per-Ractor lock never contends. The upstream writer
+  (`interlock=`) is untouched.
+
+### Fixed — `config_for` / method_missing-backed config reads die in workers (`@@options` class variable)
+
+Surfaced by the test app's `GET /features/config_probe` (rows 115/134/138:
+read the production SMTP shape, `config.x`, and `config_for(:audit)` from a
+worker).
+
+- **`Rails::Railtie::Configuration` stores its method_missing option hash in
+  the class variable `@@options`**, and Ruby 4.0 forbids ANY class-variable
+  access from a non-main Ractor (`Ractor::IsolationError: can not access
+  class variables from non-main Ractors`) — so any worker-side read of an
+  option that is not an explicit method (e.g. `config.x`) died.
+- The patch is installed with `class_eval` (NOT prepend): Ruby forbids
+  class-variable access from a prepended module ("class variable @@options
+  ... is overtaken by <module>"), and even a non-accessing worker branch
+  would be compiled into the module. Methods defined via class_eval on the
+  class itself legally own the cvar, so the main branch delegates to the
+  aliased originals — 100% upstream semantics on main.
+- Workers read through a **frozen snapshot** of the main-side `@@options`,
+  taken by the AppShareabilizer freeze pipeline (after Proc/Map/Lock
+  replacement, before the final make_shareable) and stored as the frozen
+  constant `RRS_FROZEN_OPTIONS` on the class (constants are shareable; the
+  class variable is not). Per-value `make_shareable` with rescue:
+  non-shareable leftovers (lock objects) are skipped. A per-Ractor IES
+  overlay (keyed by the config object's identity) covers worker-local
+  writes. Unknown names raise NoMethodError in workers instead of falling
+  through to the original (whose @@options access is forbidden).
+
+### Fixed — intermittent worker `NoMethodError: undefined method 'owned?'` on NoOpLock
+
+Observed ~1-in-7 kino runs on `GET /`: a worker hit
+`Concurrent::Synchronization::MutexLockableObject#synchronize`, which (since
+concurrent-ruby 1.3.8) checks `@__Lock__.owned?` before locking — and the
+shim's `NoOpLock` (the shareable stand-in swapped for `Mutex`/`Monitor`
+ivars during the graph freeze) didn't define `owned?`. Added
+`def owned?; true; end`: callers take the direct-yield path, which is the
+correct semantics for a never-contended post-boot lock.
+
+### Fixed — `normalizes` breaks every User-touching worker route (DelegateClass types poison `instance_method` cross-Ractor)
+
+Surfaced by the test app's `GET /features/normalizes_probe` (TODO P2 #3,
+row 74: `User normalizes :email, with: ->(v) { v.strip.downcase }`).
+
+- **`SerializeCastValue::ClassMethods#serialize_cast_value_compatible?` is not
+  DelegateClass-safe in workers** (`patches/activerecord.rb`): adding
+  `normalizes` to User wraps the attribute type in
+  `ActiveModel::Attributes::Normalization::NormalizedValueType`, a
+  `DelegateClass` subclass. DelegateClass defines its delegator methods via
+  `define_method` with **Proc bodies created in the defining Ractor**, and
+  Ruby 4.0 refuses `instance_method` / `instance_methods` on such classes
+  from another Ractor (`RuntimeError: defined with an un-shareable Proc in
+  a different Ractor`) — even for plain `def` methods on the same class.
+  The shim's IES-backed patch of `serialize_cast_value_compatible?` calls
+  `instance_method(...)` for every type construction, so ANY worker touching
+  User attributes boomed (Devise before_actions, mail probes, attach probes,
+  the root page, POST /posts...). The patch now rescues the cross-Ractor
+  error and recomputes with table snapshots only —
+  `method_defined?(sym, false)` per ancestor (verified safe cross-Ractor) —
+  reproducing the same first-owner comparison as upstream without Method
+  objects. Per-class IES key unchanged.
+
+### Fixed — worker-side ActiveRecord enums (row 65)
+
+Four worker-hostile method families generated by AR enums:
+
+- predicates/bangs + class-level values reader + per-value scopes are
+  define_method'd with Procs compiled inside `_enum_methods_module` (a
+  Module the proc-replacement traversal cannot reach — it walks ivars,
+  not method tables) or singleton define_method Procs capturing
+  name/value locals that workers replay with a lost binding (NameError).
+- Fix: the enum methods are re-defined as string-eval'd REAL defs (the
+  predicate compares `#{attr}_for_database`, bangs write via `update!`,
+  scopes build `all.where`/`where.not`, the pluralized reader returns a
+  const-backed frozen HWIA). Safe because Rails' `detect_enum_conflict!`
+  guarantees no user method occupies these names.
+
+### Fixed — worker-side validations silently passed everything (rows 1+98)
+
+Worker-side `valid?` returned TRUE with zero errors — invalid records
+could save in workers (data corruption). Root causes, all fixed:
+
+- The set_callback interceptor only recorded Symbol filters;
+  Validator-object filters (ActiveModel::Validator instances registered
+  by `validates` / `validates_with`) were never captured. The shim now
+  builds a shareable descriptor `{validator-class-name, attributes,
+  options, declaring-class}` and the SymbolicTransport rebuilds a fresh
+  validator in the worker and calls `.validate(record)` (return value
+  ignored — validators signal via errors, never halt).
+- Phase parsing: Rails passes the phase as filter_list[0] only when
+  explicit; no-explicit-phase declarations (`validate :sym`) were
+  silently missed (parsed per normalize_callback_params).
+- DEFAULT_KINDS was missing `:validate` (the ActiveModel validations
+  chain), and the interceptor predicate now includes ActiveRecord::Base
+  itself so Base-level declarations replay.
+
+### Fixed — DelegateClass "special" methods, ActionView date selectors, CurrentAttributes keys in workers
+
+- Ruby's delegate.rb defines every DelegateClass(X)'s "special" methods
+  (incl. `<<`) via `define_method(Delegator.delegating_block(m))` —
+  main-compiled lambdas that workers cannot call. They are detected by
+  shared source_location with a delegating-block marker and redefined as
+  string-eval'd defs. Fixes multipart parsing in workers
+  (Collector#on_mime_body calls Tempfile#<<).
+- ActionView's DateTimeSelector#sec/min/hour/day/month/year (upstream
+  `define_method(&block)`) redefined as real defs — `date_select`
+  rendered NoMethodError in workers; plus a SelectType patch for select
+  helpers.
+- CurrentAttributes' key-generated methods raised on frozen module reads
+  in workers — `Current.request_id` now round-trips.
+
+### Fixed — worker-side Solid Cache (:solid_cache_store) round-trip; connects_to pool fallback; broken `reset_table_name` super
+
+Surfaced by the test app's `GET /solid_cache_probe` (TODO #27: verify rows
+45–47 against the REAL production store instead of the kino's historical
+`:null_store` no-op path).
+
+- **Broken `super` in the `reset_table_name` patch** (`patches/activerecord.rb`):
+  the shim's ModelSchema patch was installed via
+  `ModelSchema::ClassMethods.module_eval`, which REPLACES the original
+  `reset_table_name` in place — so the override's `super` skipped past the
+  module and found nothing. Every lazy main-side `reset_table_name` after
+  patch install raised `NoMethodError: super: no superclass method
+  'reset_table_name'` (silently swallowed by the warm passes' rescues). The
+  visible victims were HABTM join models, whose table names resolve lazily
+  through the builder's `table_name_resolver` AFTER patch install: their
+  `@table_name` never materialized and the resolver lambda survived the
+  graph freeze unfrozen, so worker-side HABTM writes died with
+  `IsolationError ... (@table_name_resolver from Post::HABTM_Tags)` —
+  with a heap-layout-sensitive failure rate that made the kino flaky across
+  shim changes. The override now captures the original via `alias_method`
+  and calls it explicitly; `ShareabilityTraversal.harden_ar_model_ivars!`
+  (called right before the graph freeze) additionally materializes join-model
+  `@table_name` and freezes the resolver lambda, with loud warnings instead
+  of silent skips.
+
+- **connects_to pool fallback** (`patches/activerecord.rb`):
+  `init_worker_ar_connections!` + the patched `connection_pool` /
+  `retrieve_connection` / `connected?`. connects_to-style models (Solid
+  Cache / Solid Queue / Solid Cable) own their pool in the MAIN handler under
+  their CLASS name (`connects_to` sets `@connection_specification_name`) and
+  carry their own `default_shard` class_attribute (e.g. SolidCache::Record
+  gets `default_shard == :primary` from config/cache.yml `database: primary`),
+  while the worker handler only seeded Base-level (role, :default) pools —
+  workers querying such a model died with
+  `ConnectionNotDefined: No database connection defined for
+  SolidCache::Record with 'primary' shard`. Two fixes: (1) the worker seed
+  also registers each named env database config under its own name as a
+  shard key (the standard `connects_to database: <name>` convention), and
+  (2) the patched readers fall back to the Base-level pool for the same
+  role/shard when the class-owned pool is not present in the worker.
+- **Per-Ractor `SolidCache::Entry.select_sql` memo**
+  (`patches/solid_cache.rb`, new): the read path memoizes per-keys-count SQL
+  in the class ivar `@select_sql` — a worker cannot write class ivars
+  (IsolationError). The singleton method now routes the memo through
+  Ractor.current in workers; main keeps the original lazy-memo semantics.
+
+### Fixed — worker-Ractor mail hooks + ActiveJob `set(wait:)` enqueue; deterministic HABTM shareability
+
+Surfaced by the test app's worker-Ractor audit of mail hooks (matrix rows
+113/116) and ActiveJob enqueue options (rows 107/108). Verified by
+`GET /stats/mail_hooks_probe` (interceptor + mailer-callback headers stamped on
+worker-delivered mail) and `GET /features/job_resilience_probe`
+(`set(queue:, wait:)` enqueue + rescue-handler config readable from a worker).
+
+- **Mail hook registry snapshot** (`patches/mail.rb` +
+  `AppShareabilizer.make_shareable!`): the mail gem's
+  `inform_interceptors` / `inform_observers` read raw class variables, and the
+  shim's worker branch historically returned a per-worker EMPTY list —
+  interceptors/observers registered in main during boot silently never ran in
+  workers. The registries are now snapshotted as a frozen list of hook NAMES
+  (`RactorRailsShim::MAIL_INTERCEPTORS` / `MAIL_OBSERVERS`) AFTER the app-graph
+  freeze; workers resolve the constants and run the same hook objects main
+  registered. Non-module hooks (stateful instances) are skipped with a warning.
+  Placement note: the snapshot deliberately runs post-freeze — earlier
+  placements perturbed the heap-layout-sensitive make_shareable walk.
+- **Deterministic HABTM join-model freeze**
+  (`ShareabilityTraversal.harden_ar_model_ivars!`, called right before the
+  graph freeze): HABTM join models resolve their table name through a lazy
+  resolver lambda (`@table_name_resolver = -> { table_name }`). Whether the
+  make_shareable walk reached it was heap-layout sensitive — some
+  configurations left it unfrozen and every worker-side HABTM write
+  (`post.tags << tag`, dependent destroys) died with
+  `IsolationError ... (@table_name_resolver from Post::HABTM_Tags)`. The
+  explicit freeze (run after Proc/Map replacement cleaned the graph, so it
+  succeeds) makes worker-side HABTM deterministic.
+- **Per-Ractor Concurrent global executors**
+  (`_install_concurrent_global_timer_set_patch`): a worker-side
+  `set(wait:)` enqueue schedules via `Concurrent::ScheduledTask`, whose default
+  timer/notification path reads the unshareable `GLOBAL_TIMER_SET` /
+  `GLOBAL_IO_EXECUTOR` / `GLOBAL_FAST_EXECUTOR` constants —
+  `IsolationError: can not access non-shareable objects in constant
+  Concurrent::GLOBAL_TIMER_SET by non-main ractor`. The readers now give each
+  worker its own TimerSet / ThreadPoolExecutor through IES; main keeps the
+  global instances.
+
+### Fixed — Rails 8.1 `signed_id` / `find_signed` / `token_for` from a worker Ractor
+
+`User.find_signed(params[:token])` from a worker Ractor died with
+`NoMethodError: undefined method '[]' for ... NoOpProc`: the signed-id salt
+("active_record/signed_id") builds its verifier codec LAZILY on first use, and
+by the time a worker asks, the coordinator's rotation Proc / secret generator
+have become NoOpProcs (Proc replacement) on a frozen graph. Verified by the
+test app's `GET /features/signed_id_probe` → `generate` / `find_signed` round
+trip from a kino `:ractor` worker.
+
+- **Codec pre-warm** (`ShareabilityTraversal.prewarm_message_verifier_codecs!`,
+  called from `prepare_for_ractors!` right after the ActiveStorage prefix
+  seed): main builds the lazily-created codecs ("active_record/signed_id",
+  "active_record/token_for") up front so workers hit the frozen `@codecs`
+  cache. The salt list is deliberately method-local — load-time allocations in
+  the shim used to perturb the order-sensitive attribute-method generation
+  downstream.
+- **`SerializerWithFallback.serializer_for` NameError fix**
+  (`patches/active_support.rb`): the patch is string-eval'd on the singleton
+  class, where a bare `SERIALIZERS` reference raises NameError (cref ancestors
+  exclude the module). Now fully qualified:
+  `::ActiveSupport::Messages::SerializerWithFallback::SERIALIZERS.fetch(format)`.
+- **stdlib `JSON` default-option ivars** (`patches/make_shareable.rb`): the
+  legacy signed-id rotation passes `serializer: JSON` (stdlib), and JSON
+  memoizes `@dump_default_options` / `@load_default_options` / etc. as class
+  ivars — workers could not even read them (`IsolationError ... from JSON`).
+  Registered in `SHAREABLE_CLASS_IVARS` so they deep-freeze at prepare time.
+- **`MessageVerifier#digest_length_in_hex` memo patch**
+  (`patches/active_support.rb`): the lazily memoized `@digest_length_in_hex
+  ||=` writes to the deep-frozen verifier at first generate/verify —
+  `FrozenError: can't modify frozen ActiveSupport::MessageVerifier`. Replaced
+  with a direct `OpenSSL::Digest` computation (allocation is negligible next
+  to the HMAC itself).
+- **`ActiveRecord` attribute-state robustness** (`patches/active_model_attribute.rb`):
+  in MAIN, `attribute_types` / `_default_attributes` no longer memoize through
+  `RactorRailsShim.storage` — that memo had no invalidation path in main
+  (`reset_column_information` cannot see it), so an empty type-set built
+  before a model's schema settled poisoned `attribute_names` permanently.
+  Main now uses the upstream class-ivar memo (which every reset path clears);
+  workers keep the per-Ractor IES path.
+- **Prefix-seed ordering fix** (`roles/lifecycle.rb`): `_seed_active_storage_prefix!`
+  now runs BEFORE `install_framework_patches`. The AR model-classes patch runs
+  `load_schema` on every concrete model at install time; with the prefix
+  unseeded, ActiveStorage models computed table names like `"attachments"` and
+  the failing attempts poisoned memoized attribute state —
+  `generate_ar_attribute_methods!` then generated modules missing column
+  writers, and workers lost `ActiveStorage::Attachment#name=` (DelegationError
+  on `Attachment.new`). Seeding first closes that window.
+- Dispatch list updated in `spec/framework_patch_dispatch_spec.rb` for the new
+  `_install_message_verifier_digest_memo_patch`.
+
+### Fixed — shim TODO #5: ActiveJob `perform_later` / `deliver_later` from a worker Ractor
+
+The last code-level ❌ in `FEATURES.md`. `WelcomeJob.perform_later(user)` from
+a worker Ractor crashed with two different walls; both fixed. Regression specs
+in `spec/cgi_escape_patch_spec.rb`; verified end-to-end by the test app's
+`GET /job_enqueue_probe` → 200 `{enqueued: true, job_class: "WelcomeJob"}`
+from real kino `:ractor` workers.
+
+- **`GlobalID.app` captured via `SHAREABLE_CLASS_IVARS`** (`["GlobalID",
+  :@app]`, `patches/make_shareable.rb`). The railtie sets it to an *unfrozen*
+  String, and workers cannot even READ an unfrozen class ivar —
+  `GlobalID.create` (any ActiveJob argument serialization) died with
+  `IsolationError: can not get unshareable values from instance variables
+  ... (@app from GlobalID)` before GlobalID's own "An app is required" check
+  even ran. Deep-frozen at prepare time like the other captured ivars.
+- **New `patches/cgi.rb`** — `CGI::Escape`/`CGI::EscapeExt` default their
+  `unescape` / `unescapeURIComponent` encoding argument to the
+  `@@accept_charset` CLASS VARIABLE (the C ext impl from `cgi/escape.so`
+  reads it internally too). Ruby forbids reading class variables from
+  non-main Ractors outright — even shareable ones. globalid's URI::GID
+  parsing calls `CGI.unescape`, putting this on the enqueue path. Both
+  methods are re-defined (string eval, shareable) defaulting to a frozen
+  snapshot constant; wired into the Ractor install strategy before eager
+  load. Requires no behavior change: explicit-encoding calls keep working,
+  and the class variable storage is untouched for main-Ractor callers.
+- **`queue_adapter` needed no shim change**: ActiveJob's reader lazily
+  instantiates a per-worker adapter (`self.queue_adapter = :async if
+  _queue_adapter.nil?`) through the class_attribute IES writer, which
+  already works in workers.
+
+### Fixed — worker-Ractor cache access (low-level Rails.cache + fragment caching)
+
+Exercising the caching audit in the test app surfaced three isolation walls
+that made ANY cache call (`Rails.cache.fetch`, view fragment caching) die in a
+worker Ractor. All fixed; regression specs in
+`spec/cache_option_aliases_shareable_spec.rb`.
+
+- **`ActiveSupport::Cache::OPTION_ALIASES` registered in
+  `SHAREABLE_CONSTANTS`** (`patches/active_support.rb`). Rails freezes the
+  Hash shallowly — its Array values stay unfrozen — so workers could not even
+  READ the constant (`IsolationError` in `Store#normalize_options` →
+  `merged_options`), which broke every `fetch`/`read`/`write` with an options
+  hash. Deep-frozen at boot like the other read-only alias maps.
+- **`ActiveSupport::Cache::Coder` constants registered** (`PACKED_TYPE_
+  TEMPLATE`, `PACKED_EXPIRES_AT_TEMPLATE`, `PACKED_VERSION_LENGTH_TEMPLATE`,
+  `STRING_DESERIALIZERS`, `STRING_ENCODINGS`) — read during cache-entry
+  deserialization (`Coder#load`); the next wall behind OPTION_ALIASES.
+- **Cache serializer availability probes warmed in main**
+  (`_warm_cache_serializer_fallbacks!`, new step in the `AppShareabilizer`
+  pipeline between `_warm_attribute_method_patterns!` and
+  `_freeze_declared_callbacks!`). The `SerializerWithFallback` fallbacks
+  (Rails 8.1: `module ... extend self`) memoize `available?` as an ivar on
+  the module object; a worker making the first probe crashed on the ivar
+  WRITE (`can not set instance variables of classes/modules by non-main
+  Ractors`) during `Coder#load` → `dumped?`. Warming the probes before the
+  freeze leaves `defined?(@available)` true with a shareable boolean.
+- **`ActiveSupport::NumberHelper` converter constants registered**
+  (`NumberConverter::DEFAULTS`, `NumberToDelimitedConverter::
+  DEFAULT_DELIMITER_REGEX`, `NumberToHumanConverter::DECIMAL_UNITS` /
+  `INVERTED_DECIMAL_UNITS`, `NumberToHumanSizeConverter::STORAGE_UNITS`) —
+  read on every `number_with_delimiter` / `number_to_currency` / human-size
+  call; `DEFAULTS` was entirely unfrozen. Needed once views render number
+  helpers from worker Ractors.
+
+Verified end-to-end: the test app's fragment / russian-doll / low-level
+caching and number-helper views now serve from real kino `:ractor` workers
+(`root_load_test.rb` passes; full suite 111 runs / 0 failures / 0 skips).
+
+Verified end-to-end: the test app's kino (`:ractor` kino, production
+semantics) exercises streaming blob proxy serving, worker-side time
+zones, the error reporter, config reads, the public Active Storage
+service, the analyzer chain, and Solid Cache writes with expiry; the
+full test suite is 180 runs / 787 assertions / 0 failures and the shim
+spec suite is 804 runs / 1699 assertions / 0 failures / 4 skips.
+
+## [0.4.1]
+
+### Fixed — community-reported crash trio (GitHub issues #1, #2, #3)
+
+All three were triggered by the same docs gap: thread-mode users calling
+`prepare_for_ractors!` (Ractor-mode-only) because the README presented it
+unconditionally. Two real code defects were also exposed and fixed.
+
+- **`prepare_for_ractors!` now skips itself in thread mode** with a loud
+  warning (`roles/lifecycle.rb`). It is Ractor-mode-only: it dispatches the
+  full per-Ractor patch set and deep-freezes live Rails objects, which
+  breaks thread servers (Puma/Falcon/Thin/Webrick). Running it in thread
+  mode froze the main Ractor's live `DatabaseConfigurations::HashConfig`
+  objects → `FrozenError` in `Migration::CheckPending` on every dev HTTP
+  request. (Fixes #2; root cause of the trigger conditions in #1 and #3.)
+
+- **`SHAREABLE_AUTOSAVE_REFLECTIONS` registry swap made atomic**
+  (`patches/activerecord.rb`). `_rrs_store_autosave_reflection` removed the
+  constant before calling `Ractor.make_shareable`, so an unshareable
+  reflection (e.g. one capturing a Proc) left the constant permanently
+  missing and every later association declaration raised
+  `NameError: uninitialized constant SHAREABLE_AUTOSAVE_REFLECTIONS` on
+  boot for any app with ActiveStorage attachments. Now compute-then-swap
+  (a failure leaves the previous registry intact) plus self-healing (a
+  missing constant is re-seeded on the next store). (Fixes #1.)
+
+- **`action_methods` nil cache read fixed** in both patched copies
+  (`AbstractController::Base` and `AbstractController::UrlFor::ClassMethods`,
+  `patches/action_controller.rb`). `instance_variable_defined?` is true for
+  defined-but-nil ivars, and `clear_action_methods!` (Rails' invalidation
+  hook, hit while a mailer/controller class body is evaluated) sets
+  `@action_methods = nil` — so the next call read nil, cached nil, and
+  returned it, raising `NoMethodError: undefined method 'include?' for nil`
+  in `ActionMailer::Base#respond_to_missing?` (crashed `bin/rails
+  db:migrate` during a kamal release phase). (Fixes #3.)
+
+### Changed — docs
+- README Install section split into two explicit tracks (Ractor mode with
+  kino vs Thread mode with Puma/Falcon/Thin/Webrick), with warnings that
+  `prepare_for_ractors!` / `make_app_shareable!` must never be called in
+  thread mode.
+
 ## [0.4.0]
 
 ### Added — Rails feature support for worker Ractors