safe_memoize 1.1.0 → 1.3.0

data/README.md

@@ -67,6 +67,16 @@ SafeMemoize uses Ruby's `prepend` mechanism. When you call `memoize :method_name
 - [`memo_age` and `memo_stale?` for TTL introspection](#cache-inspection)
 - [Class-level `key:` option for shared cache key generation](#custom-cache-keys)
 - [`shared_memo_age` and `shared_memo_stale?` for shared cache TTL inspection](#shared-cache)
+- [Pluggable external cache stores — Redis, Rails.cache, or any custom adapter](#pluggable-cache-stores)
+- [Global default store via `Configuration#default_store`](#pluggable-cache-stores)
+- [`SafeMemoize::Adapters::ConcurrentRuby` — optional `concurrent-ruby` store with parallel-read locking](#concurrent-ruby-adapter)
+- [Class-level `.safe_memoize_store=` — set a per-class default store without touching global config](#class-level-default-store-safe_memoize_store)
+- [Fiber-local memoization via `fiber_local: true` — isolated per-fiber cache, no mutex, works with Async/Falcon](#fiber-local-memoization)
+- [Ractor-safe shared cache via `ractor_safe: true` — supervisor Ractor replaces the Mutex; worker Ractors can call the memoized method directly](#ractor-safe-shared-cache)
+- [Cache namespacing — per-method `namespace:`, class-level `.safe_memoize_namespace=`, and global `Configuration#namespace` for multi-tenant and versioned deployments](#cache-namespacing)
+- [Named shared caches via `shared_cache: "name"` — cross-class cache sharing backed by a globally-registered store](#named-shared-caches)
+- [Automatic cache busting via `cache_bust:` — version-token-based invalidation; works with ActiveRecord `updated_at` and any comparable value](#automatic-cache-busting)
+- [Plugin / extension architecture — `SafeMemoize::Extension` DSL for adding custom `memoize` options and global lifecycle handlers without monkey-patching](#plugin--extension-architecture)
 
 ## Installation
 
@@ -498,6 +508,48 @@ Hooks (`on_memo_hit`, `on_memo_miss`, `on_memo_expire`, `on_memo_evict`) fire on
 
 [↑ Back to features](#features)
 
+### Fiber-local memoization
+
+Pass `fiber_local: true` to store results in `Fiber[:__safe_memoize__]` rather than instance variables. Each fiber gets its own isolated cache that is automatically discarded when the fiber terminates — no explicit cleanup required.
+
+This is the right choice for Fiber-based concurrency frameworks like [Async](https://github.com/socketry/async), [Falcon](https://github.com/socketry/falcon), and Rails async controllers, where multiple fibers share the same object instance and must not see each other's cached values.
+
+```ruby
+class ApiClient
+  prepend SafeMemoize
+
+  def fetch(path)
+    http_get(path)
+  end
+
+  memoize :fetch, fiber_local: true
+end
+
+client = ApiClient.new
+
+Fiber.new { client.fetch("/a") }.resume  # computes in this fiber
+Fiber.new { client.fetch("/a") }.resume  # computes again — isolated cache
+```
+
+`fiber_local: true` works with all standard options: `ttl:`, `ttl_refresh:`, `max_size:`, `if:`, `unless:`, and `key:`. It is incompatible with `shared:` and `store:` (both raise `ArgumentError`).
+
+No `Mutex` is acquired because fibers within a single thread are cooperative — only one fiber executes at a time.
+
+**Fiber isolation guarantee**: Ruby's `Fiber.new` inherits the parent fiber's local storage by default. SafeMemoize detects inherited stores via an ownership sentinel and replaces them with a fresh, isolated store on first write, so child fibers never see the parent's cached entries.
+
+Instance-level inspection and reset for fiber-local entries use dedicated methods:
+
+```ruby
+obj.fiber_local_memoized?(:fetch, "/a")  # true / false for the current fiber
+obj.reset_fiber_memo(:fetch)             # clear all entries for :fetch in current fiber
+obj.reset_fiber_memo(:fetch, "/a")       # clear one specific entry
+obj.reset_all_fiber_memos                # clear all fiber-local entries for this instance
+```
+
+Lifecycle hooks and cache metrics work the same as for regular memoization. The existing `memoized?`, `reset_memo`, and `memo_count` methods operate on the instance-variable cache; use the `fiber_local_*` / `reset_fiber_*` API for fiber-local entries.
+
+[↑ Back to features](#features)
+
 ### Bulk memoization
 
 Use `memoize_all` to memoize every public method defined on the class in one call:
@@ -681,6 +733,282 @@ Metrics are per-instance and reset independently from the cache itself — clear
 
 [↑ Back to features](#features)
 
+### Plugin / extension architecture
+
+`SafeMemoize::Extension` lets third-party gems add custom `memoize` options and global lifecycle handlers without monkey-patching SafeMemoize internals.
+
+```ruby
+module MyExtension
+  extend SafeMemoize::Extension
+
+  # Declare a custom memoize option.
+  # The processor block runs at memoize definition time and returns
+  # a Hash of standard memoize options to inject.
+  handles_option :active_record_bust do |_value, _method_name, _options|
+    { cache_bust: -> { send(:updated_at) } }
+  end
+
+  # Register a global lifecycle handler (fires for every memoized method).
+  on_cache_event :miss do |klass, method_name, _cache_key, _record|
+    Rails.logger.debug "cache miss: #{klass}##{method_name}"
+  end
+end
+
+SafeMemoize.register_extension(:active_record_bust, MyExtension)
+```
+
+Once registered, the custom option is accepted by `memoize`:
+
+```ruby
+class OrderDecorator
+  prepend SafeMemoize
+
+  def initialize(order) = (@order = order)
+
+  def summary = expensive_compute(@order)
+  memoize :summary, active_record_bust: true
+  # ↑ MyExtension injects cache_bust: -> { updated_at } automatically
+end
+```
+
+#### `handles_option` processor return values
+
+The processor block must return a Hash of **standard** `memoize` option keys to inject. Any standard option is supported:
+
+```ruby
+handles_option :short_lived  do |ttl, _, _| { ttl: ttl }        end
+handles_option :versioned    do |ns,  _, _| { namespace: ns }    end
+handles_option :via_redis    do |store, _, _| { store: store }   end
+handles_option :bust_on      do |fn,  _, _| { cache_bust: fn }   end
+```
+
+#### `on_cache_event` handler signature
+
+```ruby
+on_cache_event :on_hit, :on_miss do |klass, method_name, cache_key, record|
+  # klass       — the class whose instance triggered the event
+  # method_name — bare Symbol (namespace stripped)
+  # cache_key   — full cache key Array
+  # record      — { value:, expires_at:, cached_at: } or nil
+end
+```
+
+Valid event types: `:on_hit`, `:on_miss`, `:on_store`, `:on_expire`, `:on_evict`.
+
+#### Registry API
+
+```ruby
+SafeMemoize.register_extension(:name, MyExtension)
+SafeMemoize.unregister_extension(:name)
+SafeMemoize.extensions               # { name: MyExtension, … }
+SafeMemoize.reset_extensions!        # clear registry (test teardown)
+SafeMemoize.extension_for_option(:active_record_bust)  # → MyExtension
+```
+
+#### Duck-type compatibility
+
+An extension does not need to `extend SafeMemoize::Extension`. Any object responding to `handled_options`, `process_memoize_option`, and `dispatch_cache_event` is accepted.
+
+#### Constraints
+
+- Unknown `memoize` keywords raise `ArgumentError` unless a registered extension claims them — typos are still caught.
+- `on_cache_event` handlers run on the main Ractor only; they are silently skipped from worker Ractors.
+
+[↑ Back to features](#features)
+
+### Automatic cache busting
+
+`cache_bust:` ties a method's cache lifetime to a version token derived from instance state. When the token changes, the old cache key no longer matches — the method is recomputed automatically, with no explicit `reset_memo` required.
+
+```ruby
+class OrderDecorator
+  prepend SafeMemoize
+
+  def initialize(order)
+    @order = order
+  end
+
+  def summary = expensive_compute(@order)
+  memoize :summary, cache_bust: -> { @order.updated_at }
+  # Saving @order advances updated_at → next call is a cache miss → fresh result
+end
+```
+
+#### Token forms
+
+```ruby
+# Proc/lambda — instance_exec gives full access to self, ivars, and methods
+memoize :report, cache_bust: -> { @record.updated_at }
+
+# Symbol — calls the named instance method
+memoize :data,   cache_bust: :cache_version
+
+# Compound token — any comparable value works, including arrays
+memoize :stats,  cache_bust: -> { [@version, tenant_id] }
+```
+
+#### How it works
+
+The token is incorporated into the cache key alongside the normal arguments. When the token changes, the old key simply produces no match — there is no deletion. Stale entries accumulate silently until:
+- They expire via `ttl:`, or
+- They are evicted by the store adapter's own eviction policy, or
+- You call `reset_memo(:method_name)` or `reset_all_memos` explicitly.
+
+For unbounded caches, pair with `ttl:` or a `max_size:`-capable store to limit memory growth:
+
+```ruby
+memoize :summary, cache_bust: -> { @order.updated_at }, ttl: 3600
+```
+
+#### Introspection
+
+All introspection methods work with the **current** token:
+
+```ruby
+obj.memoized?(:summary)       # true only if the current token's entry is live
+obj.memo_count(:summary)      # counts ALL live versions (current + stale)
+obj.reset_memo(:summary)      # clears ALL versions
+```
+
+#### Constraints
+
+- Incompatible with `key:` — both define the cache key shape; raises `ArgumentError` at `memoize` time.
+- Composes with `namespace:`, `ttl:`, `if:`, `unless:`, and `shared_cache:`.
+
+[↑ Back to features](#features)
+
+### Named shared caches
+
+`shared_cache: "name"` routes all cache reads and writes through a globally-registered store, letting unrelated classes share the same cached data without any object-level coordination.
+
+```ruby
+class OrderService
+  prepend SafeMemoize
+
+  def find(id) = Order.find(id)
+  memoize :find, shared_cache: "orders"
+end
+
+class OrderPresenter
+  prepend SafeMemoize
+
+  def find(id) = Order.find(id)          # same method signature
+  memoize :find, shared_cache: "orders"  # same backing store
+end
+
+# After OrderService.new.find(42) computes the value, OrderPresenter.new.find(42)
+# returns the cached result — the method body is not called a second time.
+```
+
+#### Registry API
+
+```ruby
+SafeMemoize.shared_cache("orders")                           # get or auto-create a Memory store
+SafeMemoize.register_shared_cache("orders", my_redis_store)  # use a custom adapter
+SafeMemoize.clear_shared_cache("orders")                     # evict all entries
+SafeMemoize.drop_shared_cache("orders")                      # remove from registry
+SafeMemoize.shared_caches                                    # { "orders" => #<Memory>, … }
+SafeMemoize.reset_shared_caches!                             # wipe registry (test teardown)
+```
+
+#### Custom adapter
+
+Register a Redis-backed (or any `Stores::Base`) store **before** any class that references the name is loaded — the store is captured at `memoize` definition time:
+
+```ruby
+# config/initializers/safe_memoize.rb
+require "safe_memoize/stores/redis"
+
+SafeMemoize.register_shared_cache(
+  "orders",
+  SafeMemoize::Stores::Redis.new(Redis.new, namespace: "myapp:orders")
+)
+```
+
+#### Key scoping and namespace composition
+
+By default two classes sharing the same cache name and method name share the same key:
+
+```ruby
+# OrderService#find(42) and OrderPresenter#find(42) → same key [:find, [42], {}]
+```
+
+Add `namespace:` when you want class-scoped entries within the same store:
+
+```ruby
+memoize :find, shared_cache: "orders", namespace: "service"    # [:"service:find", [42], {}]
+memoize :find, shared_cache: "orders", namespace: "presenter"  # [:"presenter:find", [42], {}]
+```
+
+#### Constraints
+
+- Incompatible with `shared:`, `store:`, `fiber_local:`, `ractor_safe:`, and `max_size:` (use the store adapter's own eviction policy).
+- `register_shared_cache` must be called before the class that uses the name is defined.
+- Test suites should call `SafeMemoize.reset_shared_caches!` in an `after` hook to prevent state leaking between examples.
+
+[↑ Back to features](#features)
+
+### Cache namespacing
+
+Namespacing adds a string prefix to every cache key, scoping entries to a logical partition. It is transparent to the rest of the API — introspection methods always accept and return bare method names regardless of the active namespace.
+
+Namespacing is particularly useful for:
+
+- **Versioned deployments** — change the namespace to instantly invalidate all in-flight cached values without flushing the whole store.
+- **Multi-tenant applications** — scope keys per tenant so different tenants' data cannot collide, even when sharing the same in-process hash or external store.
+
+#### Per-method namespace
+
+Pass `namespace:` to a single `memoize` call:
+
+```ruby
+class ApiClient
+  prepend SafeMemoize
+
+  def fetch(id) = http_get(id)
+  memoize :fetch, namespace: "v2"  # keys: [:"v2:fetch", [id], {}]
+end
+```
+
+#### Class-level namespace
+
+Set `.safe_memoize_namespace=` to apply a namespace to every `memoize` call on the class that doesn't specify its own:
+
+```ruby
+class OrderService
+  prepend SafeMemoize
+  self.safe_memoize_namespace = "orders"
+
+  def find(id) = Order.find(id)
+  memoize :find                       # keys: [:"orders:find", ...]
+
+  def stats = compute_stats
+  memoize :stats, namespace: "v2"     # per-method wins → [:"v2:stats", ...]
+end
+```
+
+#### Global namespace
+
+Set via `SafeMemoize.configure` to apply a namespace to every memoized method in the process that has no per-method or class-level namespace:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.namespace = "v1.2.3"   # bump this string on each deploy to bust all cached values
+end
+```
+
+#### Resolution priority
+
+`namespace:` option on `memoize` > `.safe_memoize_namespace` on the class > `SafeMemoize.configuration.namespace`
+
+#### Constraints
+
+- Namespace strings must be non-empty and must not contain `:`.
+- Namespacing works with all memoize paths (standard, `store:`, `fiber_local:`, `shared:`, `ractor_safe:`).
+- Adding or changing a namespace changes the cache keys, so existing entries become unreachable (they expire naturally or can be cleared by `reset_all_memos`).
+
+[↑ Back to features](#features)
+
 ### Global configuration
 
 Use `SafeMemoize.configure` to set defaults that apply to all subsequently memoized methods. Per-call options always take precedence over global defaults.
@@ -698,7 +1026,7 @@ Both settings apply at definition time — methods already memoized before `conf
 SafeMemoize.reset_configuration!
 ```
 
-The configure block also accepts `on_hook_error`, `on_deprecation`, `active_support_notifications`, and `statsd_client` (covered in [Hook error isolation](#hook-error-isolation), [Deprecation](#deprecation), [ActiveSupport::Notifications](#activesupportnotifications), and [StatsD](#statsd)).
+The configure block also accepts `on_hook_error`, `on_deprecation`, `active_support_notifications`, `statsd_client`, `default_store`, and `namespace` (covered in [Hook error isolation](#hook-error-isolation), [Deprecation](#deprecation), [ActiveSupport::Notifications](#activesupportnotifications), [StatsD](#statsd), [Pluggable cache stores](#pluggable-cache-stores), and [Cache namespacing](#cache-namespacing)).
 
 [↑ Back to features](#features)
 
@@ -864,6 +1192,155 @@ end
 
 [↑ Back to features](#features)
 
+### Pluggable cache stores
+
+By default, memoized results live in a per-instance hash — fast, but private to each object. Pass `store:` to route reads and writes through any external backend, enabling cross-process and distributed memoization.
+
+#### Built-in: `Stores::Memory`
+
+`Stores::Memory` is the built-in in-process store. It is used automatically by the `store:` default and is the reference implementation for custom adapters. You can pass your own instance to share a cache across multiple classes or to set a TTL on the shared store:
+
+```ruby
+SHARED_STORE = SafeMemoize::Stores::Memory.new
+
+class UserService
+  prepend SafeMemoize
+  def find(id) = User.find(id)
+  memoize :find, store: SHARED_STORE, ttl: 60
+end
+
+class PostService
+  prepend SafeMemoize
+  def author(post) = User.find(post.user_id)
+  memoize :author, store: SHARED_STORE
+end
+```
+
+The store is shared across all instances of a class, so the method is computed only once per unique argument set regardless of how many objects exist.
+
+#### Redis adapter
+
+Requires a Redis-compatible client (the `redis` gem or any drop-in replacement):
+
+```ruby
+require "safe_memoize/stores/redis"
+require "redis"
+
+REDIS_STORE = SafeMemoize::Stores::Redis.new(::Redis.new)
+
+class PricingService
+  prepend SafeMemoize
+  def quote(sku) = api_fetch(sku)
+  memoize :quote, store: REDIS_STORE, ttl: 300
+end
+```
+
+Values and keys are serialized with `Marshal` (Base64-encoded via `Array#pack("m0")`). TTL is forwarded to Redis as `PX` (milliseconds) for sub-second precision. `clear` uses `SCAN` so it never blocks the Redis event loop. All keys are namespace-scoped (default: `"safe_memoize"`) so multiple stores or applications can share one Redis instance:
+
+```ruby
+REDIS_STORE = SafeMemoize::Stores::Redis.new(::Redis.new, namespace: "myapp:memo")
+```
+
+#### Rails.cache adapter
+
+Wraps any `ActiveSupport::Cache::Store`, including `Rails.cache`:
+
+```ruby
+require "safe_memoize/stores/rails_cache"
+
+RAILS_STORE = SafeMemoize::Stores::RailsCache.new(Rails.cache)
+
+class CatalogService
+  prepend SafeMemoize
+  def fetch(slug) = Catalog.find_by!(slug: slug)
+  memoize :fetch, store: RAILS_STORE, ttl: 600
+end
+```
+
+Cached `nil` and `false` values are distinguished from a cache miss via a sentinel envelope, so falsy results are preserved correctly. TTL is forwarded as `expires_in:` for native store expiry. `clear` uses `delete_matched` scoped to the namespace.
+
+#### Custom adapters
+
+Subclass `SafeMemoize::Stores::Base` and implement the six-method contract:
+
+```ruby
+class MyStore < SafeMemoize::Stores::Base
+  def read(key)         = ...  # return MISS if absent
+  def write(key, value, expires_in: nil) = ...
+  def delete(key)       = ...
+  def clear             = ...
+  def keys              = ...  # Array of stored keys
+end
+```
+
+Use `SafeMemoize::Stores::Base::MISS` (a frozen sentinel object) as the return value from `read` when the key is absent — this distinguishes a cache miss from a cached `nil` or `false`.
+
+#### concurrent-ruby adapter
+
+`SafeMemoize::Adapters::ConcurrentRuby` replaces the default `Mutex`-backed store with `Concurrent::Map` and `Concurrent::ReentrantReadWriteLock` from the [`concurrent-ruby`](https://github.com/ruby-concurrency/concurrent-ruby) gem. Multiple readers proceed in parallel; writers still get exclusive access. For read-heavy hot paths this can meaningfully reduce lock contention.
+
+`concurrent-ruby` is a **soft dependency** — it is not required at runtime unless you instantiate the adapter. Add it to your own `Gemfile`:
+
+```ruby
+gem "concurrent-ruby"
+```
+
+Opt in per class:
+
+```ruby
+class HotService
+  prepend SafeMemoize
+  self.safe_memoize_store = SafeMemoize::Adapters::ConcurrentRuby.new
+
+  def expensive(id) = db.find(id)
+  memoize :expensive
+end
+```
+
+Or set it globally:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.default_store = SafeMemoize::Adapters::ConcurrentRuby.new
+end
+```
+
+A `LoadError` with an actionable message is raised at instantiation if `concurrent-ruby` is not installed. The adapter is incompatible with `max_size:` and `shared:` (same constraints as all external stores).
+
+#### Class-level default store (`safe_memoize_store=`)
+
+Set a default store for every `memoize` call on a single class without touching the global configuration:
+
+```ruby
+class ReportService
+  prepend SafeMemoize
+  self.safe_memoize_store = SafeMemoize::Adapters::ConcurrentRuby.new
+
+  def summary = compute_summary   # routed through ConcurrentRuby
+  memoize :summary
+end
+```
+
+The resolution order is: per-method `store:` → class-level `.safe_memoize_store` → global `SafeMemoize.configuration.default_store`. Assign `nil` to clear. An invalid value (not a `Stores::Base` instance) raises `ArgumentError`.
+
+#### Global default store
+
+Set a default store for all compatible `memoize` calls without specifying `store:` on each one:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.default_store = SafeMemoize::Stores::Redis.new(::Redis.new)
+end
+```
+
+A per-method `store:` option always takes precedence. Methods using `max_size:` or `shared:` silently bypass the global default (LRU and shared-mode use their own storage). An invalid value raises `ArgumentError` at `memoize` time. Reset with `SafeMemoize.reset_configuration!`.
+
+#### Compatibility
+
+The `store:` option composes with `ttl:`, `ttl_refresh:`, `if:`, `unless:`, lifecycle hooks, and cache metrics. It is incompatible with `max_size:` (use the store adapter's own eviction) and `shared:` (raise `ArgumentError` if combined).
+
+[↑ Back to features](#features)
+
 ### Deprecation
 
 SafeMemoize ships a structured deprecation helper for gem authors who build on top of it:
@@ -895,17 +1372,72 @@ end
 
 [↑ Back to features](#features)
 
+## Ractor-safe shared cache
+
+Pass `ractor_safe: true` (together with `shared: true`) to replace the `Mutex`-backed class-level shared cache with a supervisor `Ractor` that owns the mutable cache hash. All reads and writes are serialised through message passing, so the cache is safe to use from multiple Ractors.
+
+```ruby
+class PriceService
+  prepend SafeMemoize
+
+  def fetch_price(item_id)
+    external_api.get("/prices/#{item_id}")
+  end
+
+  memoize :fetch_price, shared: true, ractor_safe: true, ttl: 300
+end
+
+# Main Ractor — multiple threads share one cache entry
+20.times.map { Thread.new { PriceService.new.fetch_price(42) } }.map(&:value)
+
+# Worker Ractors also read from and write to the same supervisor cache
+result = Ractor.new(PriceService) { |s| s.new.fetch_price(42) }.take
+```
+
+### How it works
+
+- A **supervisor `Ractor`** is created once per class the first time a `ractor_safe: true` method is memoized. It owns a plain Ruby `Hash` and responds to `:fetch`, `:store`, `:delete_all`, `:delete_one`, `:clear`, `:memoized`, and `:count` messages.
+- The memoize **wrapper Proc** is frozen via `Ractor.make_shareable` before being registered with `define_method`, so the class can be passed directly into `Ractor.new` blocks.
+- Cached values are deep-frozen via `Ractor.make_shareable`. Values that cannot be made shareable (e.g. a `Mutex`) raise `ArgumentError`.
+- **Thread safety** inside the main Ractor (multiple threads) is handled by per-call tags (`Thread.current.object_id`) combined with `Ractor.receive_if`, so concurrent threads never consume each other's replies.
+- `ttl:` is supported. Expired entries are skipped by the supervisor's `:fetch` handler.
+
+### Constraints
+
+`ractor_safe: true` is intentionally limited. The following options are incompatible and raise `ArgumentError` at `memoize` time:
+
+| Option | Reason |
+|---|---|
+| `if:` / `unless:` | Conditional Procs are non-Ractor-shareable |
+| `max_size:` | LRU order tracking requires a non-shareable Ruby `Hash` |
+| `ttl_refresh:` | Requires re-examining the record on every hit |
+| `key:` | Custom key Procs are non-Ractor-shareable |
+| `store:` | External adapters are incompatible with the supervisor model |
+
+### Class-level API
+
+```ruby
+PriceService.ractor_memoized?(:fetch_price, 42)     # → true / false
+PriceService.ractor_memo_count                       # → total live entries
+PriceService.ractor_memo_count(:fetch_price)         # → entries for one method
+PriceService.reset_ractor_memo(:fetch_price, 42)     # → clear one entry
+PriceService.reset_ractor_memo(:fetch_price)         # → clear all entries for method
+PriceService.reset_all_ractor_memos                  # → clear entire shared cache
+```
+
+[↑ Back to features](#features)
+
 ## Ractor compatibility
 
-SafeMemoize is **not Ractor-compatible** in its current form. Passing a class that uses `memoize` into a `Ractor.new` block raises `RuntimeError: defined with an un-shareable Proc in a different Ractor`. There are two root causes:
+Regular `memoize` (without `ractor_safe: true`) is **not Ractor-compatible**. Passing a class that uses `memoize` into a `Ractor.new` block raises `RuntimeError: defined with an un-shareable Proc in a different Ractor`. There are two root causes:
 
 1. **Non-shareable closures.** `ClassMethods#memoize` builds anonymous modules using `define_method` with blocks that close over local variables (`ttl`, `max_size`, `condition`, `shared_mutex`, …). Ruby marks those Procs as non-Ractor-shareable, so the host class cannot be sent to a Ractor.
 
-2. **Mutable module-level state.** `SafeMemoize.configuration` reads `@configuration` from the `SafeMemoize` module — a mutable ivar on a shared constant — which raises `Ractor::IsolationError` from a non-main Ractor. This affects every memoized call because hooks and adapters always read the configuration.
+2. **Mutable module-level state.** `SafeMemoize.configuration` reads `@configuration` from the `SafeMemoize` module — a mutable ivar on a shared constant — which raises `Ractor::IsolationError` from a non-main Ractor.
 
-**Workaround:** Use Ruby Threads instead of Ractors — SafeMemoize is fully thread-safe via double-check locking and per-instance Mutexes. If you need true parallelism with Ractors, perform computation inside the Ractor without memoization and send frozen results back via `Ractor#send`.
+**Workaround for shared caches:** use `memoize :method, shared: true, ractor_safe: true` (see [Ractor-safe shared cache](#ractor-safe-shared-cache) above).
 
-Ractor support is tracked in the v1.0.0 roadmap. The fix would require replacing closed-over variables with frozen shareable bindings and making `Configuration` a frozen value object, which is a significant redesign.
+**Workaround for per-instance caches:** Use Ruby Threads instead of Ractors — SafeMemoize is fully thread-safe via double-check locking and per-instance Mutexes. If you need true parallelism with Ractors, perform computation inside the Ractor without memoization and send frozen results back via `Ractor#send`.
 
 ## Development
 
@@ -970,6 +1502,17 @@ Anything **not** listed here — internal modules, private methods, `@__safe_mem
 | `SafeMemoize.configuration` | module method | Returns the current `Configuration` |
 | `SafeMemoize.reset_configuration!` | module method | Restores all configuration to defaults |
 | `SafeMemoize.deprecate(subject, message:, horizon:)` | module method | Emits a structured deprecation warning |
+| `SafeMemoize.shared_cache(name)` | module method | Returns named store, auto-creating a `Memory` store if absent |
+| `SafeMemoize.register_shared_cache(name, store)` | module method | Registers a custom `Stores::Base` under a name |
+| `SafeMemoize.clear_shared_cache(name)` | module method | Evicts all entries from the named store |
+| `SafeMemoize.drop_shared_cache(name)` | module method | Removes the named store from the registry |
+| `SafeMemoize.shared_caches` | module method | Returns a snapshot of the registry |
+| `SafeMemoize.reset_shared_caches!` | module method | Clears the entire registry (test teardown) |
+| `SafeMemoize.register_extension(name, ext)` | module method | Registers a plugin extension |
+| `SafeMemoize.unregister_extension(name)` | module method | Removes an extension |
+| `SafeMemoize.extensions` | module method | Returns snapshot of extension registry |
+| `SafeMemoize.reset_extensions!` | module method | Clears all extensions (test teardown) |
+| `SafeMemoize.extension_for_option(name)` | module method | Returns the extension handling the named option |
 
 ### `memoize` DSL (class method, added by `prepend SafeMemoize`)
 
@@ -982,6 +1525,13 @@ Anything **not** listed here — internal modules, private methods, `@__safe_mem
 | `unless:` | `Symbol \| Proc \| nil` | `nil` | Store only when falsy |
 | `shared:` | `Boolean` | `false` | Class-level shared cache |
 | `key:` | `Proc \| nil` | `nil` | Class-level custom key generator |
+| `store:` | `Stores::Base \| nil` | `nil` | External cache store adapter; incompatible with `max_size:` and `shared:` |
+| `fiber_local:` | `Boolean` | `false` | Fiber-local cache; each fiber gets an isolated store; incompatible with `shared:` and `store:` |
+| `ractor_safe:` | `Boolean` | `false` | Supervisor-Ractor shared cache; replaces the `Mutex`; worker Ractors can call the method; requires `shared: true`; cached values are deep-frozen; incompatible with `if:`, `unless:`, `max_size:`, `ttl_refresh:`, `key:`, and `store:` |
+| `namespace:` | `String \| nil` | `nil` | Namespace prefix prepended to the cache key's first element; must not contain `:`; takes precedence over the class-level and global namespace |
+| `shared_cache:` | `String \| nil` | `nil` | Name of a globally-registered shared store; incompatible with `shared:`, `store:`, `fiber_local:`, `ractor_safe:`, and `max_size:` |
+| `cache_bust:` | `Proc \| Symbol \| nil` | `nil` | Version-token callable; invoked on the instance at each lookup; token is folded into the key; incompatible with `key:` |
+| *(extension options)* | any | — | Unknown kwargs are validated against registered extensions; raise `ArgumentError` if unclaimed |
 
 ### `memoize_all` options (class method)
 
@@ -1055,6 +1605,14 @@ All `memoize` option keys above, plus:
 | `memoize_with_custom_key(method_name) { \|*args, **kwargs\| … }` | Instance-level key generator |
 | `clear_custom_keys(method_name = nil)` | Remove one or all key generators |
 
+**Fiber-local cache (when any method uses `fiber_local: true`)**
+
+| Method | Returns |
+|---|---|
+| `fiber_local_memoized?(method_name, *args, **kwargs)` | `Boolean` — cached in the current fiber? |
+| `reset_fiber_memo(method_name, *args, **kwargs)` | `nil` — clear one or all entries in current fiber |
+| `reset_all_fiber_memos` | `nil` — clear all fiber-local entries for this instance |
+
 ### Shared-cache class methods (added when any method uses `shared: true`)
 
 | Method | Returns |
@@ -1066,6 +1624,15 @@ All `memoize` option keys above, plus:
 | `shared_memo_age(method_name, *args, **kwargs)` | `Numeric \| nil` |
 | `shared_memo_stale?(method_name, *args, **kwargs)` | `Boolean` |
 
+**Ractor-safe shared cache (added when any method uses `ractor_safe: true`)**
+
+| Method | Returns |
+|---|---|
+| `reset_ractor_memo(method_name, *args, **kwargs)` | `nil` — clear one or all entries |
+| `reset_all_ractor_memos` | `nil` — clear the entire Ractor-safe shared cache |
+| `ractor_memoized?(method_name, *args, **kwargs)` | `Boolean` — live entry exists? |
+| `ractor_memo_count(method_name = nil)` | `Integer` — live entry count |
+
 ### `SafeMemoize::Configuration` attributes
 
 | Attribute | Type | Default |
@@ -1077,10 +1644,21 @@ All `memoize` option keys above, plus:
 | `active_support_notifications` | `Boolean` | `false` |
 | `statsd_client` | `Object \| nil` | `nil` |
 | `opentelemetry_tracer` | `Object \| nil` | `nil` |
+| `default_store` | `Stores::Base \| nil` | `nil` |
+| `namespace` | `String \| nil` | `nil` |
+
+### Store adapter classes (v1.1.0+)
+
+| Class | Require | Notes |
+|---|---|---|
+| `SafeMemoize::Stores::Base` | auto | Abstract base — subclass to build custom adapters; exposes `MISS` sentinel |
+| `SafeMemoize::Stores::Memory` | auto | Built-in in-process store; reference implementation |
+| `SafeMemoize::Stores::Redis` | `"safe_memoize/stores/redis"` | Redis-backed adapter; Marshal serialization; `PX` TTL |
+| `SafeMemoize::Stores::RailsCache` | `"safe_memoize/stores/rails_cache"` | `ActiveSupport::Cache::Store` wrapper |
 
 ### Opt-in extensions (not guaranteed until their owning milestone ships)
 
-The following are available now but reside under `require "safe_memoize/rails"` and are not covered by the v1.0.0 semver guarantee until the v1.x milestone that owns them is declared stable:
+The following are available now but reside under `require "safe_memoize/rails"` and are not covered by the semver guarantee until the v1.x milestone that owns them is declared stable:
 
 - `SafeMemoize::Rails` module (`track`, `reset_tracked!`)
 - `SafeMemoize::Rails::RequestScoped` concern