safe_memoize 1.6.0 → 1.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1920c31de4a855b818c5a4f37f35260f38489b7ff6ffe221b43d91e862133bde
-  data.tar.gz: 948979dfc49f4e42b16d21926344869fc06a39da3252ab1033697a5748a7362a
+  metadata.gz: 0b2558ad027e3b8bb09ec956d8a18eed759b56c9baa1234a173fdebd7e5e9913
+  data.tar.gz: ae5302c29efe49c336a323bc7a6ad8dcd4a6b10cebc394e786fccd12c00a66ab
 SHA512:
-  metadata.gz: 415c4095ce702b5823a887858f342fdf5742887394dc2cc113ccf711ef1f5789430e036d69ee3660d663a2153f34375f3622f1ff92d73143072e2376d2ae087b
-  data.tar.gz: 1fed071b0feb6591d4b95c69604f4c14440c88cefbdb13ce9f2e50a2eba5fad4723b28c1584f2cb7aaa33f7ba4e2140b5a16c45b99ba0cd9b13f47b2a16b0d58
+  metadata.gz: 5822061de749e6001cee636a687c19bfd59253ed075b4d9e82123aa88954578a3a8f2dcd0a5a9cbfb29cad8d86b6768a5461a454210dfd7bf56ba624e4e6df6c
+  data.tar.gz: 89e21d16cb9e37a00333f98ec12adf7b9ec6a3e746bb1a9f8377cfafd16c27abbd92de5a79074e207f51fcacaa25a0e9c58092da94a82798be501d35a677489c

data/.github/workflows/ci.yml

@@ -34,6 +34,9 @@ jobs:
   test:
     name: Ruby ${{ matrix.ruby }}
     runs-on: ubuntu-latest
+    # Normal runs finish in under a minute; fail fast if the suite hangs
+    # (default is 6 hours).
+    timeout-minutes: 10
     strategy:
       fail-fast: false
       matrix:
@@ -55,6 +58,12 @@ jobs:
       - name: Run test suite
         run: bundle exec rake spec
 
+      # SimpleCov marks :nocov: lines as "ignored"; Codecov rejects non-numeric
+      # line values and discards the whole report, so treat them as non-lines.
+      - name: Normalize ignored lines for Codecov
+        if: matrix.ruby == '3.4'
+        run: sed -i 's/"ignored"/null/g' coverage/coverage.json
+
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v5
         if: matrix.ruby == '3.4'
@@ -62,3 +71,25 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: coverage/coverage.json
 
+      # The upload step succeeds even when Codecov later fails to process the
+      # report (state "error", 0% coverage), so poll the API and fail loudly.
+      - name: Verify Codecov processed the report
+        if: matrix.ruby == '3.4' && github.event.pull_request.head.repo.fork != true
+        env:
+          SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: |
+          owner="${GITHUB_REPOSITORY%%/*}"
+          repo="${GITHUB_REPOSITORY#*/}"
+          url="https://api.codecov.io/api/v2/github/${owner}/repos/${repo}/commits/${SHA}/"
+          for attempt in $(seq 1 18); do
+            state=$(curl -fsS "$url" | jq -r '.state' || true)
+            echo "Codecov state for ${SHA}: ${state:-unknown} (attempt ${attempt})"
+            case "$state" in
+              complete) exit 0 ;;
+              error)
+                echo "::error::Codecov failed to process the coverage report for ${SHA}"
+                exit 1 ;;
+            esac
+            sleep 10
+          done
+          echo "::warning::Timed out waiting for Codecov to process ${SHA}"

data/CHANGELOG.md

@@ -8,6 +8,22 @@ from v1.0.0 onwards. Prior 0.x releases may include breaking changes between min
 
 ## [Unreleased]
 
+## [1.7.1] - 2026-10-26
+
+### Fixed
+
+- `ractor_safe: true` could hang forever on Ruby 3.x when several threads in the same Ractor called memoized methods (or `reset_all_ractor_memos` and friends) at once. Ruby can lose a wakeup when multiple threads wait in `Ractor.receive_if` on the Ractor's single incoming queue, leaving one caller blocked indefinitely. Each request/reply round trip to the supervisor is now serialized per Ractor; throughput is unchanged since the supervisor already handles requests one at a time.
+- `ractor_safe: true` now works on Ruby 4.0. Ruby 4.0 removed `Ractor.receive_if` and `Ractor#take`, so every call raised `NoMethodError`. On 4.0 each request now gets its own `Ractor::Port` for the supervisor's reply; Ruby 3.x behaviour is unchanged. The `ractor_safe` specs previously skipped themselves on 4.0 and now run there.
+
+## [1.7.0] - 2026-06-02
+
+### Added
+
+- `SafeMemoize::Stores::Multilevel` — multi-level (L1/L2/…) cache store that checks faster layers first and promotes values from deeper layers into shallower ones on a miss ("read-through promotion"). Reads walk the list from first (fastest) to last; writes go to every level simultaneously; deletes and clears apply to all levels. Accepts `promote_expires_in:` to control the TTL of promoted entries (default: no TTL, relying on the L1 store's own eviction). Raises `ArgumentError` if fewer than two stores are supplied.
+- `store: [l1, l2]` shorthand on `memoize` — passing an `Array` of `Stores::Base` instances is automatically converted to `Stores::Multilevel.new(*stores)`, enabling multi-level caching without explicit wrapper construction.
+- `SafeMemoize::Stores::XFetch` — wraps any `Stores::Base` adapter with probabilistic early expiry (the XFetch algorithm) to prevent cache stampedes. Values are stored with an envelope that includes `expires_at`; on read the XFetch formula `now − (delta × beta × log(rand)) ≥ expires_at` decides whether to return the value or `MISS` (triggering early recomputation). Configurable via `beta:` (aggressiveness scalar, default 1.0) and `delta:` (estimated computation time in seconds, default 0.1). Composes naturally with `Multilevel` and `CircuitBreaker`.
+- `stampede_protection:` option on `memoize` — enables the XFetch algorithm for the per-instance in-process cache. Pass `true` (default beta 1.0) or a `Numeric` for a custom beta. Records actual computation time as `delta` on each miss so the XFetch probability adapts to real observed latency. Requires `ttl:`. Incompatible with `store:` (use `Stores::XFetch` for external stores) and `ractor_safe:`. Accepted by `safe_memoize_options` as a class-wide default.
+
 ## [1.6.0] - 2026-06-02
 
 ### Added
@@ -259,7 +275,18 @@ from v1.0.0 onwards. Prior 0.x releases may include breaking changes between min
 
 - Initial release
 
-[Unreleased]: https://github.com/eclectic-coding/safe_memoize/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/eclectic-coding/safe_memoize/compare/v1.7.1...HEAD
+[1.7.1]: https://github.com/eclectic-coding/safe_memoize/compare/v1.7.0...v1.7.1
+[1.7.0]: https://github.com/eclectic-coding/safe_memoize/compare/v1.6.0...v1.7.0
+[1.6.0]: https://github.com/eclectic-coding/safe_memoize/compare/v1.5.0...v1.6.0
+[1.5.0]: https://github.com/eclectic-coding/safe_memoize/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/eclectic-coding/safe_memoize/compare/v1.3.0...v1.4.0
+[1.3.0]: https://github.com/eclectic-coding/safe_memoize/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/eclectic-coding/safe_memoize/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/eclectic-coding/safe_memoize/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/eclectic-coding/safe_memoize/compare/v0.9.0...v1.0.0
+[0.9.0]: https://github.com/eclectic-coding/safe_memoize/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/eclectic-coding/safe_memoize/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/eclectic-coding/safe_memoize/compare/v0.6.3...v0.7.0
 [0.6.3]: https://github.com/eclectic-coding/safe_memoize/compare/v0.6.2...v0.6.3
 [0.6.2]: https://github.com/eclectic-coding/safe_memoize/compare/v0.6.1...v0.6.2

data/README.md

@@ -12,6 +12,57 @@ SafeMemoize is a production-ready, zero-dependency memoization library for Ruby.
 
 Beyond the basics, SafeMemoize ships with TTL expiration (including sliding window refresh via `ttl_refresh:`), LRU cache size capping, conditional caching via `if:`/`unless:` predicates, lifecycle hooks for cache hits, evictions, and expirations, per-instance metrics (hit rate, miss rate, average computation time), targeted and bulk cache invalidation, custom cache key generators, and rich introspection helpers (`memoized?`, `memo_count`, `memo_keys`, `memo_values`, `memo_ttl_remaining`). It preserves method visibility (public, protected, and private) and requires no runtime dependencies.
 
+## Table of Contents
+
+- [The Problem](#the-problem)
+- [How It Works](#how-it-works)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic memoization](#basic-memoization)
+  - [With arguments](#with-arguments)
+  - [Nil and false safety](#nil-and-false-safety)
+  - [Works with private methods](#works-with-private-methods)
+  - [Cache reset](#cache-reset)
+  - [Cache invalidation groups](#cache-invalidation-groups)
+  - [Lifecycle hooks](#lifecycle-hooks)
+  - [TTL expiration](#ttl-expiration)
+  - [Sliding window TTL](#sliding-window-ttl)
+  - [LRU cache size limit](#lru-cache-size-limit)
+  - [Conditional caching](#conditional-caching)
+  - [Cache warm-up and persistence](#cache-warm-up-and-persistence)
+  - [Shared cache](#shared-cache)
+  - [Fiber-local memoization](#fiber-local-memoization)
+  - [Bulk memoization](#bulk-memoization)
+  - [Custom cache keys](#custom-cache-keys)
+  - [Cache inspection](#cache-inspection)
+  - [Cache metrics](#cache-metrics)
+  - [Plugin / extension architecture](#plugin--extension-architecture)
+  - [Automatic cache busting](#automatic-cache-busting)
+  - [Named shared caches](#named-shared-caches)
+  - [Cache namespacing](#cache-namespacing)
+  - [Global configuration](#global-configuration)
+  - [ActiveSupport::Notifications](#activesupportnotifications)
+  - [StatsD](#statsd)
+  - [OpenTelemetry](#opentelemetry)
+  - [Rails request-scope](#rails-request-scope)
+  - [Pluggable cache stores](#pluggable-cache-stores)
+  - [Deprecation](#deprecation)
+- [Circuit breaker for external stores](#circuit-breaker-for-external-stores)
+- [Multi-level caching](#multi-level-caching)
+- [Stampede protection](#stampede-protection)
+- [Per-class default options](#per-class-default-options-safe_memoize_options)
+- [Copy-on-read](#copy-on-read)
+- [Ractor-safe shared cache](#ractor-safe-shared-cache)
+- [Ractor compatibility](#ractor-compatibility)
+- [Development](#development)
+- [Releasing](#releasing)
+- [Public API and versioning guarantee](#public-api-and-versioning-guarantee)
+- [Ruby version support](#ruby-version-support)
+- [Benchmarks](benchmarks/BENCHMARK.md)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## The Problem
 
 Ruby's common memoization pattern breaks with falsy values: 
@@ -28,60 +79,6 @@ SafeMemoize uses `Hash#key?` to distinguish "not yet cached" from "cached nil/fa
 
 SafeMemoize uses Ruby's `prepend` mechanism. When you call `memoize :method_name`, it creates an anonymous module with a wrapper method and prepends it onto your class. The wrapper calls `super` to invoke the original method and stores the result in a per-instance hash. Thread safety is achieved with a per-instance `Mutex` using double-check locking.
 
-## Features
-
-- [Correctly memoizes `nil` and `false` return values](#nil-and-false-safety)
-- [Caches per unique arguments (positional and keyword)](#with-arguments)
-- [Thread-safe via double-check locking](#how-it-works)
-- [Simple `prepend` + `memoize` API](#usage)
-- [Preserves public, protected, and private method visibility](#works-with-private-methods)
-- [Supports targeted cache invalidation by argument combination](#cache-reset)
-- [Includes a `memoized?` helper for cache inspection](#cache-inspection)
-- [Includes a `memo_count` helper for cache size stats](#cache-inspection)
-- [Includes a `memo_keys` helper for inspecting cached signatures](#cache-inspection)
-- [Includes a `memo_values` helper for inspecting cached signatures and values](#cache-inspection)
-- [Optional TTL expiration support for cached entries](#ttl-expiration)
-- [Sliding window TTL via `ttl_refresh: true`](#sliding-window-ttl)
-- [Optional LRU cache size limit per method via `max_size:`](#lru-cache-size-limit)
-- [Conditional caching via `if:` and `unless:` predicates](#conditional-caching)
-- [Lifecycle hooks for hit, miss, eviction, and expiration events](#lifecycle-hooks)
-- [Per-instance cache metrics (hit rate, miss rate, computation time)](#cache-metrics)
-- [Cache warm-up, export, and restore (`warm_memo`, `dump_memo`, `load_memo`)](#cache-warm-up-and-persistence)
-- [Class-level shared cache via `shared: true` with optional LRU](#shared-cache)
-- [Bulk memoization via `memoize_all` (public, protected, and private)](#bulk-memoization)
-- [Custom cache key generation per method](#custom-cache-keys)
-- [TTL introspection via `memo_ttl_remaining`](#cache-inspection)
-- [Deep single-entry inspection via `memo_inspect`](#cache-inspection)
-- [`ArgumentError` at definition time when memoizing an undefined method](#basic-memoization)
-- [Hook error isolation — hook exceptions never propagate to callers](#lifecycle-hooks)
-- [Deprecation infrastructure for gem authors](#deprecation)
-- [Optional `ActiveSupport::Notifications` integration for Rails observability](#activesupportnotifications)
-- [Optional StatsD adapter for metrics pipelines](#statsd)
-- [Optional OpenTelemetry adapter for distributed tracing](#opentelemetry)
-- [Rails request-scope helpers for controllers and service objects](#rails-request-scope)
-- [Batch cache warm-up via `memo_preload`](#cache-warm-up-and-persistence)
-- [`on_memo_store` hook fires on every cache write](#lifecycle-hooks)
-- [Global default TTL and max size via `SafeMemoize.configure`](#global-configuration)
-- [`memo_touch` resets the expiry clock without recomputing](#ttl-expiration)
-- [`memo_refresh` force-recomputes and re-caches in one call](#cache-inspection)
-- [`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)
-- [Per-class default options via `safe_memoize_options` — set TTL, max size, copy-on-read, and other defaults for every `memoize` call on the class without repeating them](#per-class-default-options-safe_memoize_options)
-- [Copy-on-read via `copy_on_read: true` — returns a `dup`/`deep_dup` on every cache read to protect shared cached state from caller mutation](#copy-on-read)
-- [Cache invalidation groups via `group:` — tag related methods with a group name and bust them all with a single `reset_memo_group` call](#cache-invalidation-groups)
-- [Circuit breaker for external stores — `Stores::CircuitBreaker` wraps any store adapter and falls back to the per-instance cache when the store is down; configurable error threshold and probe interval](#circuit-breaker-for-external-stores)
-
 ## Installation
 
 Add to your Gemfile:
@@ -120,7 +117,7 @@ end
 
 Calling `memoize` on a method name that does not exist raises `ArgumentError` immediately at class definition time rather than at the first runtime call.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### With arguments
 
@@ -145,7 +142,7 @@ calc.compute(3, 4)  # computes and caches (different args)
 
 Argument arrays, hashes, and strings are deep-frozen into an independent copy when the cache key is built, so mutating arguments after a call cannot corrupt or miss a cached entry.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Nil and false safety
 
@@ -161,7 +158,7 @@ class Config
 end
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Works with private methods
 
@@ -182,7 +179,7 @@ class TokenProvider
 end
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Cache reset
 
@@ -194,7 +191,7 @@ obj.reset_memo(:search, "ruby", page: 2)       # Clears one positional/keyword c
 obj.reset_all_memos                             # Clears all memoized values
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Cache invalidation groups
 
@@ -267,7 +264,7 @@ end
 
 A method belongs to at most one group at a time; re-memoizing with a different `group:` moves it.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Lifecycle hooks
 
@@ -345,7 +342,7 @@ end
 
 Set `c.on_hook_error = :raise` to re-raise exceptions instead of swallowing them.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### TTL expiration
 
@@ -377,7 +374,7 @@ obj.memo_refresh(:current_quote)             # Recomputes and re-caches
 obj.memo_refresh(:find, 42)                  # Recomputes for one argument combination
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Sliding window TTL
 
@@ -396,7 +393,7 @@ end
 
 Without `ttl_refresh:`, the entry expires 300 seconds after it was first cached. With it, the clock resets on every read — the entry is evicted only if the method goes 300 seconds without being called. `ttl_refresh: true` requires `ttl:` to be set and works with both per-instance and `shared: true` memoization.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### LRU cache size limit
 
@@ -431,7 +428,7 @@ memoize :find, max_size: 50, ttl: 300
 
 The `on_evict` hook fires for LRU-evicted entries the same way it does for manual `reset_memo` calls.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Conditional caching
 
@@ -467,7 +464,7 @@ Both options accept any callable and compose with `ttl:` and `max_size:`:
 memoize :find, if: ->(result) { !result.nil? }, ttl: 60, max_size: 500
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Cache warm-up and persistence
 
@@ -533,7 +530,7 @@ obj.load_memo(Marshal.load(raw)) if raw
 
 Loaded entries have no TTL — they persist until explicitly reset. Expired entries are excluded from `dump_memo` output, so snapshots never contain stale data.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Shared cache
 
@@ -583,7 +580,7 @@ memoize :find, shared: true, max_size: 500
 
 Hooks (`on_memo_hit`, `on_memo_miss`, `on_memo_expire`, `on_memo_evict`) fire on the calling instance as usual.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Fiber-local memoization
 
@@ -625,7 +622,7 @@ obj.reset_all_fiber_memos                # clear all fiber-local entries for thi
 
 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)
+[↑ Back to top](#table-of-contents)
 
 ### Bulk memoization
 
@@ -683,7 +680,7 @@ memoize_all include_protected: true, include_private: true
 
 Inherited methods are never affected regardless of visibility.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Custom cache keys
 
@@ -732,7 +729,7 @@ svc.clear_custom_keys(:generate)  # Remove generator for one method
 svc.clear_custom_keys             # Remove all custom key generators
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Cache inspection
 
@@ -778,7 +775,7 @@ obj.memo_inspect(:find, 42)
 
 Returns `nil` when the entry is not cached.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Cache metrics
 
@@ -808,7 +805,7 @@ obj.cache_metrics_reset(:find)    # Clears metrics for one method only
 
 Metrics are per-instance and reset independently from the cache itself — clearing metrics does not evict cached values.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Plugin / extension architecture
 
@@ -891,7 +888,7 @@ An extension does not need to `extend SafeMemoize::Extension`. Any object respon
 - 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)
+[↑ Back to top](#table-of-contents)
 
 ### Automatic cache busting
 
@@ -952,7 +949,7 @@ obj.reset_memo(:summary)      # clears ALL versions
 - 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)
+[↑ Back to top](#table-of-contents)
 
 ### Named shared caches
 
@@ -1023,7 +1020,7 @@ memoize :find, shared_cache: "orders", namespace: "presenter"  # [:"presenter:fi
 - `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)
+[↑ Back to top](#table-of-contents)
 
 ### Cache namespacing
 
@@ -1084,7 +1081,7 @@ end
 - 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)
+[↑ Back to top](#table-of-contents)
 
 ### Global configuration
 
@@ -1105,7 +1102,7 @@ SafeMemoize.reset_configuration!
 
 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)
+[↑ Back to top](#table-of-contents)
 
 ### ActiveSupport::Notifications
 
@@ -1147,7 +1144,7 @@ end
 
 The integration is a no-op when ActiveSupport is not loaded — there is no overhead for non-Rails projects. `active_support_notifications` defaults to `false`.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### StatsD
 
@@ -1173,7 +1170,7 @@ Each call includes two tags: `method:method_name` and `class:ClassName`. The cli
 
 If the client raises, the error is rescued and a warning is emitted to stderr rather than propagated to the caller. `statsd_client` defaults to `nil` (disabled).
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### OpenTelemetry
 
@@ -1198,7 +1195,7 @@ SafeMemoize then wraps every cache miss (the actual method call, not cache hits)
 
 Cache hits produce no spans, so tracing overhead is zero for cached calls. The adapter is compatible with any tracer that responds to `in_span(name, attributes:, &block)` — the interface provided by `opentelemetry-sdk`, `opentelemetry-api`, and no-op tracers alike. If `opentelemetry_tracer` is `nil` (the default), the adapter is completely bypassed.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Rails request-scope
 
@@ -1267,7 +1264,7 @@ end
 
 `SafeMemoize::Rails::Middleware` calls `reset_all_memos` on every tracked instance in the current thread at the end of the request, even if the app raises. Tracking is thread-local, so concurrent requests never interfere. The tracked list is cleared automatically after each reset.
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ### Pluggable cache stores
 
@@ -1416,7 +1413,7 @@ A per-method `store:` option always takes precedence. Methods using `max_size:`
 
 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)
+[↑ Back to top](#table-of-contents)
 
 ### Deprecation
 
@@ -1447,7 +1444,7 @@ SafeMemoize.configure do |c|
 end
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ## Circuit breaker for external stores
 
@@ -1531,7 +1528,103 @@ class ApiService
 end
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
+
+## Multi-level caching
+
+`SafeMemoize::Stores::Multilevel` chains two or more store adapters from fastest (L1) to slowest. Reads walk the chain until a hit is found; on a miss in an earlier layer the value is fetched from the next layer and written back ("promoted") into all shallower layers. Writes and deletes reach every layer.
+
+```ruby
+l1 = SafeMemoize::Stores::Memory.new          # fast, in-process
+l2 = MyRedisStore.new                          # slower, cross-process
+
+class ProductService
+  prepend SafeMemoize
+
+  def catalog = fetch_catalog_from_db
+  memoize :catalog, store: [l1, l2], ttl: 300  # Array shorthand
+end
+```
+
+The `store: [l1, l2]` shorthand is equivalent to `store: Stores::Multilevel.new(l1, l2)`.
+
+### Promotion TTL
+
+By default promoted entries have no TTL (the L1 store's own eviction — e.g. LRU — handles memory bounds). Set `promote_expires_in:` to give L1 entries a shorter lifetime than L2:
+
+```ruby
+store = SafeMemoize::Stores::Multilevel.new(l1, l2, promote_expires_in: 60)
+memoize :catalog, store: store, ttl: 300
+```
+
+### Composition
+
+`Multilevel` composes with `CircuitBreaker` and `XFetch`:
+
+```ruby
+safe_l2 = SafeMemoize::Stores::CircuitBreaker.new(MyRedisStore.new)
+store   = SafeMemoize::Stores::Multilevel.new(SafeMemoize::Stores::Memory.new, safe_l2)
+memoize :catalog, store: store, ttl: 300
+```
+
+[↑ Back to top](#table-of-contents)
+
+## Stampede protection
+
+Cache stampedes (a.k.a. thundering-herd) happen when a popular entry expires and many processes simultaneously recompute it. SafeMemoize offers two mechanisms:
+
+### `stampede_protection:` — per-instance cache
+
+The `stampede_protection:` option applies the **XFetch algorithm** to the per-instance in-process cache. Instead of expiring at a hard deadline, each cache read probabilistically triggers early recomputation as the entry approaches its TTL:
+
+```ruby
+class ApiClient
+  prepend SafeMemoize
+
+  def catalog = fetch_catalog
+  memoize :catalog, ttl: 300, stampede_protection: true   # default beta=1.0
+  # or
+  memoize :catalog, ttl: 300, stampede_protection: 2.0    # custom beta (more aggressive)
+end
+```
+
+The measured computation time from each cache miss is stored as `delta` and used in subsequent reads, so the XFetch probability adapts to real observed latency automatically.
+
+**Requirements:** `ttl:` must be set. Incompatible with `store:` (see `Stores::XFetch` below) and `ractor_safe:`.
+
+### `Stores::XFetch` — external stores
+
+For external stores (Redis, Rails.cache, etc.) wrap the adapter with `Stores::XFetch`. Values are stored with an `expires_at` envelope so the wrapper can apply the formula even though the store's `read` returns only the plain value:
+
+```ruby
+store = SafeMemoize::Stores::XFetch.new(
+  MyRedisStore.new,
+  delta: 0.2,   # estimated typical computation time (seconds)
+  beta:  1.5    # aggressiveness scalar
+)
+
+class CatalogService
+  prepend SafeMemoize
+
+  def products = db_fetch
+  memoize :products, store: store, ttl: 300
+end
+```
+
+**XFetch formula:** `now − (delta × beta × log(rand)) ≥ expires_at`
+
+A higher `beta` triggers early recomputation more aggressively. A larger `delta` (longer computation) also increases the recomputation window.
+
+`Stores::XFetch` composes with `Multilevel` and `CircuitBreaker`:
+
+```ruby
+store = SafeMemoize::Stores::XFetch.new(
+  SafeMemoize::Stores::CircuitBreaker.new(MyRedisStore.new),
+  delta: 0.1
+)
+```
+
+[↑ Back to top](#table-of-contents)
 
 ## Per-class default options (`safe_memoize_options`)
 
@@ -1570,7 +1663,7 @@ Call with no arguments to clear all class-level defaults:
 MyClass.safe_memoize_options   # clears — subsequent memoize calls use global config or per-call options only
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ## Copy-on-read
 
@@ -1608,7 +1701,7 @@ class ReportService
 end
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ## Ractor-safe shared cache
 
@@ -1629,7 +1722,7 @@ end
 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
+result = Ractor.new(PriceService) { |s| s.new.fetch_price(42) }.value  # .take on Ruby 3.x
 ```
 
 ### How it works
@@ -1637,7 +1730,7 @@ result = Ractor.new(PriceService) { |s| s.new.fetch_price(42) }.take
 - 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.
+- **Thread safety** inside the main Ractor (multiple threads): on Ruby 4.0+ each call replies through its own `Ractor::Port`, so callers never share a queue. On Ruby 3.x, replies are matched by per-call tags (`Thread.current.object_id`) with `Ractor.receive_if`, and each send/receive pair is serialized per Ractor because concurrent `receive_if` waiters can otherwise lose a wakeup and hang.
 - `ttl:` is supported. Expired entries are skipped by the supervisor's `:fetch` handler.
 
 ### Constraints
@@ -1663,7 +1756,7 @@ PriceService.reset_ractor_memo(:fetch_price)         # → clear all entries for
 PriceService.reset_all_ractor_memos                  # → clear entire shared cache
 ```
 
-[↑ Back to features](#features)
+[↑ Back to top](#table-of-contents)
 
 ## Ractor compatibility
 
@@ -1681,7 +1774,7 @@ Regular `memoize` (without `ractor_safe: true`) is **not Ractor-compatible**. Pa
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt.
 
-To run the benchmark suite: `bundle exec ruby benchmarks/benchmark.rb`.
+To run the benchmark suite: `bundle exec ruby benchmarks/benchmark.rb`. Pre-recorded results and analysis are in [benchmarks/BENCHMARK.md](benchmarks/BENCHMARK.md).
 
 To generate API documentation locally: `bundle exec rake doc`. Output is written to `doc/` (gitignored). The online reference is published automatically to [RubyDoc.info](https://rubydoc.info/gems/safe_memoize) on every release. Install `memery` and `memo_wise` first if you want comparison columns against those gems.
 
@@ -1772,6 +1865,7 @@ Anything **not** listed here — internal modules, private methods, `@__safe_mem
 | `copy_on_read:` | `Boolean` | `false` | Return a `dup`/`deep_dup` of the cached value on every read; protects shared state from caller mutation; nil and frozen values pass through; incompatible with `ractor_safe:` |
 | `group:` | `Symbol \| String \| nil` | `nil` | Assigns the method to a named invalidation group; call `reset_memo_group` / `reset_shared_memo_group` to bust all methods in the group at once; a method belongs to at most one group |
 | `circuit_breaker:` | `true \| Hash \| nil` | `nil` | Wraps the configured `store:` in a `Stores::CircuitBreaker`; `true` uses defaults (`error_threshold: 5`, `probe_interval: 30`); pass a Hash to customise; requires a store to be set; does not double-wrap |
+| `stampede_protection:` | `true \| Numeric \| nil` | `nil` | Enables XFetch probabilistic early expiry on the per-instance cache; `true` uses beta=1.0; pass a `Numeric` for a custom beta; requires `ttl:`; incompatible with `store:` and `ractor_safe:` |
 | *(extension options)* | any | — | Unknown kwargs are validated against registered extensions; raise `ArgumentError` if unclaimed |
 
 ### `memoize_all` options (class method)
@@ -1789,7 +1883,7 @@ All `memoize` option keys above, plus:
 
 | Option key | Type | Default | Notes |
 |---|---|---|---|
-| any `memoize` key except mode-switches | — | — | Accepts `ttl:`, `max_size:`, `ttl_refresh:`, `if:`, `unless:`, `key:`, `cache_bust:`, `copy_on_read:`, `namespace:`, `store:`, `group:`, `circuit_breaker:`; raises `ArgumentError` for `shared:`, `fiber_local:`, `ractor_safe:`, `shared_cache:` |
+| any `memoize` key except mode-switches | — | — | Accepts `ttl:`, `max_size:`, `ttl_refresh:`, `if:`, `unless:`, `key:`, `cache_bust:`, `copy_on_read:`, `namespace:`, `store:`, `group:`, `circuit_breaker:`, `stampede_protection:`; raises `ArgumentError` for `shared:`, `fiber_local:`, `ractor_safe:`, `shared_cache:` |
 
 ### Instance methods (public)
 

data/ROADMAP.md

@@ -4,17 +4,6 @@ This document tracks the planned evolution of SafeMemoize through v1.0.0 and bey
 
 ---
 
-## v1.7.0 — Advanced Store Features
-
-*Goal: multi-process performance patterns for high-traffic deployments.*
-
-| Feature | Description | Status |
-|---|---|---|
-| Multi-level (L1/L2) caching | `store: [memory_store, redis_store]` — check in-process first, fall back to the remote store on miss, and promote to L1 on read; each level can have independent TTL and eviction settings | Planned |
-| Stampede protection | Probabilistic early expiry (XFetch algorithm) for external stores; recomputes slightly before a TTL expires to prevent multiple processes hitting a cold miss simultaneously | 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.*