safe_memoize 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6beffd3f5a1de6f8582c9a164502f353b8ac6c55caec6326edb4c52b0bf913ec
-  data.tar.gz: 44ebaf0f89254c692b9d33d8962577c9644df6d910818905e46395ba5e28cf89
+  metadata.gz: 24faf0555ba5e11e37092aea14e1db090d7f5bb13dd40edc33ea30d8adcba552
+  data.tar.gz: '09beaa5cf9e25284462bdac9636929642213a9e8d657900d30913832da230959'
 SHA512:
-  metadata.gz: 0f22cd22816499ec3400a7b98cf51c3a3b77a43a0e26451ff97d6f01877d02df8772b7b3be0209e86b5c6c00d435bc96e7db8fd3a28619169e1f0e97b8ab0263
-  data.tar.gz: af315893620e46fe419a2a61ff4092f7d27f71bbfe98185ba0714162148c7d19b2d31ed9db3909d500f3e12f474f51d66ec027d81cd2d7e9948e4bc388d3a5db
+  metadata.gz: 8ed21a58fc95a122794bcb91a1cbccae2bad598b38f736d76eb6f95551245dba070e047eaaea56b26fca6aace181e138acd37a0a027dbb7c0a6a43ae728f2cf0
+  data.tar.gz: f51afd15884dd10c771cd3f3ffcb7d481b0fd3012ecc74148fc9ff82e056abc1a2bb044d5344d635abb5380d200f0ec62a4db528d8fc79697358f775cc4aba3e

data/.github/workflows/ci.yml

@@ -53,12 +53,12 @@ jobs:
           bundler-cache: true
 
       - name: Run test suite
-        run: bundle exec rspec
+        run: bundle exec rake spec
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v5
         if: matrix.ruby == '3.4'
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
-          files: coverage/.resultset.json
+          files: coverage/coverage.json
 

data/CHANGELOG.md

@@ -8,7 +8,48 @@ from v1.0.0 onwards. Prior 0.x releases may include breaking changes between min
 
 ## [Unreleased]
 
-## [1.0.0] - 2026-05-22
+## [1.2.0] - 2026-05-27
+
+### Added
+
+- `SafeMemoize::Adapters::ConcurrentRuby` — optional store adapter backed by `concurrent-ruby`; uses `Concurrent::Map` as the backing hash and `Concurrent::ReentrantReadWriteLock` to allow multiple readers to proceed in parallel while writers still get exclusive access; reduces lock contention on hot read paths compared to the default `Mutex`-backed `Stores::Memory`; `concurrent-ruby` is a soft dependency — a `LoadError` with an actionable message is raised at instantiation if the gem is not available
+- `.safe_memoize_store=` / `.safe_memoize_store` — class-level attribute for setting a default store on an individual class without touching the global `SafeMemoize.configure` default; takes precedence over `SafeMemoize.configuration.default_store` but is overridden by a per-method `store:` argument; accepts any `SafeMemoize::Stores::Base` instance or `nil`; raises `ArgumentError` for invalid values
+
+- `ractor_safe: true` option on `memoize` — replaces 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; requires `shared: true`; cached values are deep-frozen via `Ractor.make_shareable`; the memoize wrapper Proc is frozen with `Ractor.make_shareable` before being passed to `define_method` so that classes using `ractor_safe: true` can be passed directly into worker Ractors; incompatible with `if:`, `unless:`, `max_size:`, `ttl_refresh:`, `key:`, and `store:` (raises `ArgumentError`); `ttl:` is supported
+- `.reset_ractor_memo(method_name, *args, **kwargs)` — class method to clear one or all entries from the Ractor-safe shared cache for a given method
+- `.reset_all_ractor_memos` — class method to clear the entire Ractor-safe shared cache for this class
+- `.ractor_memoized?(method_name, *args, **kwargs)` — returns `true` if a live entry exists in the Ractor-safe shared cache for the given call signature
+- `.ractor_memo_count(method_name = nil)` — returns the number of live entries in the Ractor-safe shared cache; scoped to one method when a name is given
+- `fiber_local: true` option on `memoize` — stores results in `Fiber[:__safe_memoize__]` rather than instance variables, giving each fiber its own isolated cache that is automatically discarded when the fiber terminates; no `Mutex` is acquired because fibers are cooperative; a per-fiber ownership sentinel ensures inherited storage from parent fibers is replaced with a fresh isolated store on first write; supports all standard options (`ttl:`, `ttl_refresh:`, `max_size:`, `if:`, `unless:`, `key:`); incompatible with `shared:` and `store:` (raises `ArgumentError`)
+- `#fiber_local_memoized?(method_name, *args, **kwargs)` — returns `true` if the given call is currently cached in the current fiber's store
+- `#reset_fiber_memo(method_name, *args, **kwargs)` — clears one or all fiber-local cached entries for a method in the current fiber
+- `#reset_all_fiber_memos` — clears all fiber-local cached entries for this instance in the current fiber
+
+### Fixed
+
+- `call_memo_hooks` no longer raises `Ractor::IsolationError` when called from a worker Ractor — `SafeMemoize.configuration` (a module-level ivar) is now accessed only from the main Ractor; `ActiveSupport::Notifications` and `StatsD` dispatch are silently skipped from worker Ractors; hook-error handling falls back to `warn` rather than reading the configuration handler
+- CI coverage ordering — ractor specs now run *last* (after all other specs) so that Ractor background threads cannot disrupt Ruby's Coverage counters while collecting coverage for non-Ractor code; previously only store specs were ordered first
+- Codecov reporting accuracy — switched SimpleCov output from `.resultset.json` (internal format, misread by Codecov as ~85%) to `coverage/coverage.json` via `simplecov_json_formatter`; CI now uploads the correct file
+- CI coverage ordering — `bundle exec rspec` ran files alphabetically, causing `ractor_spec.rb` to execute before `spec/stores/`, disrupting Ruby's Coverage counters and dropping reported coverage to ~96%; CI now uses `bundle exec rake spec`, which enforces the store-first ordering already documented in the Rakefile
+
+## [1.1.0] - 2026-05-22
+
+### Added
+
+- `SafeMemoize::Stores::Base` — abstract adapter base class defining the cache store contract: `read(key)`, `write(key, value, expires_in: nil)`, `delete(key)`, `clear`, `keys`, and `exist?(key)`; a frozen `MISS` sentinel on `Base` distinguishes cache misses from cached `nil` or `false` values; `exist?` has a default implementation that delegates to `read`
+- `SafeMemoize::Stores::Memory` — built-in in-process store that wraps a plain `Hash` behind a `Mutex`; supports per-entry TTL via `expires_in:` with lazy expiry on read; serves as both the default store and the reference implementation for custom adapters
+- `Configuration#default_store` — set via `SafeMemoize.configure { |c| c.default_store = MyStore.new }` to route every `memoize` call that has no explicit `store:` through the given adapter; methods using `max_size:` or `shared:` are incompatible and fall back silently to the per-instance hash; an invalid value raises `ArgumentError` at `memoize` time; cleared by `reset_configuration!`
+- `SafeMemoize::Stores::RailsCache` — opt-in adapter (`require "safe_memoize/stores/rails_cache"`) wrapping any `ActiveSupport::Cache::Store` (including `Rails.cache`); values are wrapped in a sentinel envelope so cached `nil`/`false` are distinguished from a cache miss; TTL forwarded as `expires_in:` for native store expiry; `clear` uses `delete_matched` scoped to the namespace; `keys` returns `[]` (AS::Cache has no enumeration API)
+- `SafeMemoize::Stores::Redis` — opt-in adapter (`require "safe_memoize/stores/redis"`) backed by any Redis-compatible client responding to `#get`, `#set`, `#del`, and `#scan_each`; values and keys are serialized with Marshal + `pack("m0")`; TTL is forwarded as `PX` (milliseconds, rounded up) for sub-second precision; `clear` uses `SCAN` to avoid blocking; all entries are namespaced (default: `"safe_memoize"`) so multiple stores or applications can share one Redis instance
+- `store:` option on `memoize` — accepts any `Stores::Base` subclass instance; routes all reads and writes through the adapter's `read`/`write` interface; the store is shared across all instances of the class; `ttl:` is forwarded as `expires_in:` to `write`, `ttl_refresh:` re-writes on every hit, and `if:`/`unless:` conditional storage is enforced at the SafeMemoize layer; raises `ArgumentError` if combined with `max_size:` (LRU belongs in the adapter) or `shared:`
+
+### Changed
+
+- Test suite achieves 100% line coverage — `spec_helper` now requires opt-in store adapters (`Stores::Redis`, `Stores::RailsCache`) after `SimpleCov.start` so Coverage tracks them; `Rakefile` runs `spec/stores/` before other specs to prevent Ruby 3.4 Coverage counter disruption from Ractor/concurrency tests; `version.rb` excluded from coverage reporting
+- `store:` type guard in `ClassMethods#memoize` collapsed to an inline guard clause so Ruby's Coverage module counts the raise correctly
+- Hook-error isolation tests (`concurrency_spec`, `hooks_spec`) now configure `on_hook_error = ->(*) {}` to silence expected stderr warnings rather than leaking them into test output; StatsD error-resilience test asserts on the emitted warning with `expect { }.to output(...).to_stderr`
+
+## [1.0.0] - 2026-05-22 
 
 ### Added
 

data/README.md

@@ -67,6 +67,12 @@ 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)
 
 ## Installation
 
@@ -498,6 +504,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:
@@ -698,7 +746,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`, and `default_store` (covered in [Hook error isolation](#hook-error-isolation), [Deprecation](#deprecation), [ActiveSupport::Notifications](#activesupportnotifications), [StatsD](#statsd), and [Pluggable cache stores](#pluggable-cache-stores)).
 
 [↑ Back to features](#features)
 
@@ -864,6 +912,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 +1092,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
 
@@ -982,6 +1234,9 @@ 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:` |
 
 ### `memoize_all` options (class method)
 
@@ -1055,6 +1310,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 +1329,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 +1349,20 @@ 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` |
+
+### 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

data/ROADMAP.md

@@ -4,48 +4,6 @@ This document tracks the planned evolution of SafeMemoize through v1.0.0 and bey
 
 ---
 
-## v1.0.0 — Stable API
-
-*Goal: declare a stable, semver-governed public API that downstream code can depend on with confidence.*
-
-| Feature | Description | Status |
-|---|---|---|
-| Semantic versioning guarantee | Document which constants, methods, and option keys are public API; breaking changes require a major bump henceforth | Shipped |
-| Complete RBS + Sorbet signatures | Cover all public methods including overloads for optional keyword arguments; publish `.rbi` stubs as a companion package if demand warrants | Shipped |
-| Full API reference | Generated documentation hosted on RubyDoc or a dedicated docs site; all public methods documented with parameter types, return values, and usage examples | Shipped |
-| Ractor compatibility audit | Investigate and either support Ractor-compatible operation (Mutex replacement, shared-cache storage) or document the limitation clearly | Shipped |
-| Ruby version policy | Formalise the supported Ruby version window and cadence for dropping EOL versions | Shipped |
-| Deprecation sweep | Resolve or formally deprecate any unstable internal APIs before the stable release | Shipped |
-| Upgrade guide | Document all breaking changes from 0.x and provide a migration path for users of deprecated behaviour | Shipped |
-
----
-
-## v1.1.0 — Pluggable Cache Stores
-
-*Goal: allow the in-process hash cache to be swapped for an external store, enabling cross-process and distributed memoization.*
-
-| Feature | Description | Status |
-|---|---|---|
-| Cache store adapter interface | Define a minimal read/write/delete/clear/keys contract that external backends must implement | Planned |
-| `store:` option on `memoize` | Accept any store adapter object; defaults to the existing in-process hash store | Planned |
-| Redis adapter | Reference implementation (`SafeMemoize::Stores::Redis`) with TTL, LRU-like expiry, and serialization handled transparently | Planned |
-| Rails.cache adapter | Thin wrapper around `ActiveSupport::Cache::Store` for projects already using a configured Rails cache | Planned |
-| Global default store | Set via `SafeMemoize.configure` — applies a default store to every memoized method without per-call configuration | Planned |
-
----
-
-## v1.2.0 — Async & Fiber-Safe Memoization
-
-*Goal: first-class support for Fiber-based concurrency frameworks (Async, Falcon, Rails async controllers).*
-
-| Feature | Description | Status |
-|---|---|---|
-| Fiber-local memoization mode | `memoize :method, fiber_local: true` stores results in `Fiber[:safe_memoize_cache]` rather than instance variables, giving each fiber its own isolated cache automatically reset when the fiber terminates | Planned |
-| Ractor-compatible shared cache | Revisit `shared: true` using `Ractor::TVar` or shareable frozen objects so class-level caches work across Ractors | Planned |
-| concurrent-ruby integration | Optional adapter using `Concurrent::Map` and `Concurrent::ReentrantReadWriteLock` as a drop-in replacement for `Mutex` where higher read-concurrency is desirable | Planned |
-
----
-
 ## v2.0.0 — Next Generation (Long Horizon)
 
 *Goal: incorporate real-world usage feedback, clean up accumulated API surface, and open a path for advanced extension.*

data/Rakefile

@@ -3,7 +3,19 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:spec) do |t|
+  # Ordering ensures accurate coverage tracking in Ruby 3.4:
+  # 1. Store specs first: opt-in adapter lines must be hit before Ractor tests
+  #    can disrupt Ruby's Coverage counters.
+  # 2. Ractor specs last: Ractor-based tests spin up background Ractors whose
+  #    internal threads can cause later coverage samples to be missed if they
+  #    interleave with SimpleCov's collection phase.
+  store_specs = Dir["spec/stores/**/*_spec.rb"].sort
+  ractor_specs = Dir["spec/ractor*_spec.rb"].sort
+  other_specs = Dir["spec/**/*_spec.rb"].sort - store_specs - ractor_specs
+  t.rspec_opts = (store_specs + other_specs + ractor_specs).join(" ")
+  t.pattern = "non_existent_placeholder" # overridden by rspec_opts file args
+end
 
 require "standard/rake"
 

data/lib/safe_memoize/adapters/concurrent_ruby.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Adapters
+    # Optional store adapter backed by +concurrent-ruby+.
+    #
+    # Replaces the default +Mutex+-guarded +Hash+ with +Concurrent::Map+ and
+    # +Concurrent::ReentrantReadWriteLock+. Multiple readers proceed in parallel;
+    # writers still get exclusive access. For hot paths with many concurrent readers
+    # this can meaningfully reduce lock contention compared to {Stores::Memory}.
+    #
+    # Opt in per class:
+    #
+    #   class MyService
+    #     prepend SafeMemoize
+    #     self.safe_memoize_store = SafeMemoize::Adapters::ConcurrentRuby.new
+    #   end
+    #
+    # Or globally via {SafeMemoize.configure}:
+    #
+    #   SafeMemoize.configure do |c|
+    #     c.default_store = SafeMemoize::Adapters::ConcurrentRuby.new
+    #   end
+    #
+    # Requires the +concurrent-ruby+ gem, which is *not* a runtime dependency of
+    # +safe_memoize+. Add it to your own Gemfile or gemspec:
+    #
+    #   gem "concurrent-ruby"
+    #
+    # A {LoadError} with an actionable message is raised at instantiation time if
+    # the gem is not available.
+    class ConcurrentRuby < Stores::Base
+      def initialize
+        require "concurrent/map"
+        require "concurrent/atomic/reentrant_read_write_lock"
+        @data = Concurrent::Map.new
+        @lock = Concurrent::ReentrantReadWriteLock.new
+      rescue LoadError
+        raise LoadError,
+          "SafeMemoize::Adapters::ConcurrentRuby requires the concurrent-ruby gem. " \
+          "Add `gem 'concurrent-ruby'` to your Gemfile."
+      end
+
+      # @param key [Object]
+      # @return [Object] the stored value, or {MISS} if absent or expired
+      def read(key)
+        @lock.with_read_lock do
+          entry = @data[key]
+          return MISS unless entry
+          return MISS if expired?(entry)
+
+          entry[:value]
+        end
+      end
+
+      # @param key [Object]
+      # @param value [Object]
+      # @param expires_in [Numeric, nil] seconds until expiry; +nil+ means no expiry
+      # @return [void]
+      def write(key, value, expires_in: nil)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        expires_at = expires_in ? now + expires_in.to_f : nil
+        @lock.with_write_lock do
+          @data[key] = {value: value, expires_at: expires_at, cached_at: now}
+        end
+      end
+
+      # @param key [Object]
+      # @return [void]
+      def delete(key)
+        @lock.with_write_lock { @data.delete(key) }
+      end
+
+      # @return [void]
+      def clear
+        @lock.with_write_lock { @data.clear }
+      end
+
+      # Returns all live (non-expired) keys.
+      # @return [Array<Object>]
+      def keys
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @lock.with_read_lock do
+          result = []
+          @data.each_pair { |k, entry| result << k unless entry[:expires_at] && entry[:expires_at] <= now }
+          result
+        end
+      end
+
+      private
+
+      def expired?(entry)
+        expires_at = entry[:expires_at]
+        expires_at && expires_at <= Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end