safe_memoize 1.6.0 → 1.7.1

data/benchmarks/BENCHMARK.md

@@ -0,0 +1,114 @@
+# SafeMemoize Benchmark Results
+
+Run with `bundle exec ruby benchmarks/benchmark.rb`.
+
+**Environment:** Ruby 3.4.8 (arm64-darwin25, PRISM) · `benchmark-ips` 5 s measurement / 2 s warmup
+
+---
+
+## What is being measured
+
+SafeMemoize is compared against two vanilla Ruby baselines:
+
+| Label | Pattern | Correctness |
+|---|---|---|
+| `raw \|\|= (unsafe)` | `@v \|\|= compute` | Broken — re-runs if result is `nil` or `false` |
+| `raw safe ivar` | `return @v if defined?(@v); @v = compute` | Correct |
+| `safe_memoize` | `prepend SafeMemoize` + `memoize :method` | Correct |
+
+The raw patterns are intentionally simple and carry none of SafeMemoize's feature overhead (thread safety, argument keying, TTL, hooks, metrics). The numbers below quantify exactly what that feature set costs.
+
+---
+
+## Results
+
+### 1. Zero-arg cache HIT — steady-state throughput
+
+A primed object called repeatedly. This is the hot path.
+
+| Implementation | i/s | ns/call | vs fastest |
+|---|---|---|---|
+| `raw safe ivar` | 21.51 M | 46.5 | — |
+| `raw \|\|= (unsafe)` | 16.69 M | 59.9 | 1.29× slower |
+| `safe_memoize` | 296.8 K | 3,370 | **72×** slower |
+
+**Takeaway:** SafeMemoize's hit path costs ~3.4 µs per call — the price of a hash lookup, mutex check, and key construction. For methods that are called millions of times per second in a tight loop, raw ivars win. For methods that do real work (DB queries, HTTP, serialization), this overhead is negligible.
+
+---
+
+### 2. Zero-arg cache MISS — first-call overhead
+
+A fresh instance is created each iteration so every call is a miss.
+
+| Implementation | i/s | µs/call | vs fastest |
+|---|---|---|---|
+| `raw safe ivar` | 8.47 M | 0.12 | — |
+| `safe_memoize` | 189.6 K | 5.28 | **45×** slower |
+
+**Takeaway:** The miss path allocates the cache hash, builds the key, and acquires the mutex — ~5 µs. Still fast in absolute terms; any method body doing more than a trivial computation will dominate.
+
+---
+
+### 3. With-argument cache HIT — keyed lookup
+
+A primed object called with the same argument each iteration.
+
+| Implementation | i/s | ns/call | vs fastest |
+|---|---|---|---|
+| `raw safe ivar` | 14.17 M | 70.6 | — |
+| `safe_memoize` | 289.2 K | 3,460 | **49×** slower |
+
+**Takeaway:** The argument hash lookup adds roughly the same overhead as the zero-arg case. Key construction (deep-freeze copy of args) dominates, not the hash lookup itself.
+
+---
+
+### 4. Fast path vs locked path (internal)
+
+Both are `safe_memoize`. Adding `max_size:` enables LRU tracking, which holds the mutex for the full read/write cycle.
+
+| Configuration | i/s | µs/call | vs fast path |
+|---|---|---|---|
+| No `max_size:` (fast path) | 287.7 K | 3.48 | — |
+| `max_size: 100` (locked path) | 218.0 K | 4.59 | 1.32× slower |
+
+**Takeaway:** LRU costs an extra ~1.1 µs per hit. Use it when eviction matters; skip it for unbounded caches.
+
+---
+
+### 5. Shared cache vs instance cache (internal)
+
+Both are `safe_memoize`. `shared: true` stores results on the class rather than the instance.
+
+| Configuration | i/s | µs/call | difference |
+|---|---|---|---|
+| Instance cache | 292.5 K | 3.42 | — |
+| Shared cache | 275.3 K | 3.63 | within margin of error |
+
+**Takeaway:** Class-level shared storage is essentially free compared to per-instance caching. The mutex contention at the class level does not measurably affect single-threaded throughput.
+
+---
+
+### 6. Concurrent throughput — 8 threads × 50,000 iterations
+
+| Implementation | Total time | i/s |
+|---|---|---|
+| `raw safe ivar` | 0.033 s | 12.01 M |
+| `safe_memoize` (instance cache) | 1.363 s | 293.4 K |
+| `safe_memoize` (shared cache) | 1.393 s | 287.1 K |
+
+**Takeaway:** Under real thread contention the raw ivar baseline has no locking at all — it is technically unsafe here. SafeMemoize's per-instance mutex serialises writes correctly at ~293 K i/s; the class-level shared mutex performs identically at ~287 K i/s.
+
+---
+
+## Summary
+
+| Scenario | SafeMemoize overhead |
+|---|---|
+| Hot cache hit (zero-arg) | ~3.4 µs — 72× vs raw ivar |
+| Hot cache hit (with args) | ~3.5 µs — 49× vs raw ivar |
+| First call / cache miss | ~5.3 µs — 45× vs raw ivar |
+| LRU enabled (`max_size:`) | +1.1 µs vs fast path |
+| Shared vs instance cache | no measurable difference |
+| Concurrent throughput | ~293 K i/s (thread-safe) |
+
+SafeMemoize is slower than a raw instance variable in absolute terms, but the overhead is measured in **microseconds**, not milliseconds. Any method that does I/O, calls a database, hits an external API, or performs non-trivial computation will completely dominate the memoization overhead — and that is precisely the use case SafeMemoize is designed for.

data/benchmarks/README.md

@@ -65,4 +65,6 @@ bundle exec ruby benchmarks/benchmark.rb
    safe_memoize (shared) ~323 K i/s
 ```
 
-Results vary by hardware, Ruby version, and GVL scheduling. Run on your own hardware for authoritative numbers.
+Results vary by hardware, Ruby version, and GVL scheduling. Run on your own hardware for authoritative numbers.
+
+For a full recorded run with analysis, see [BENCHMARK.md](BENCHMARK.md).

data/lib/safe_memoize/cache_record_methods.rb

@@ -22,8 +22,10 @@ module SafeMemoize
       Process.clock_gettime(Process::CLOCK_MONOTONIC) + ttl
     end
 
-    def memo_record(value, expires_at:)
-      {value: value, expires_at: expires_at, cached_at: Process.clock_gettime(Process::CLOCK_MONOTONIC)}
+    def memo_record(value, expires_at:, delta: nil)
+      rec = {value: value, expires_at: expires_at, cached_at: Process.clock_gettime(Process::CLOCK_MONOTONIC)}
+      rec[:delta] = delta if delta
+      rec
     end
 
     def memo_record_value(record)

data/lib/safe_memoize/class_methods.rb

@@ -74,6 +74,12 @@ module SafeMemoize
     #   +probe_interval: 30+), or a +Hash+ with +:error_threshold+ and/or +:probe_interval+
     #   keys to customise. Requires a +store:+ to be set (per-method, class-level, or
     #   global default); raises +ArgumentError+ otherwise.
+    # @param stampede_protection [Boolean, Numeric, nil] enables probabilistic early
+    #   expiry (XFetch algorithm) on the per-instance in-process cache. Pass +true+ to
+    #   use the default beta scalar (1.0), or a +Numeric+ to set a custom beta. A higher
+    #   beta causes early recomputation to trigger more aggressively. Requires +ttl:+ to
+    #   be set. Incompatible with +store:+ (use {Stores::XFetch} instead) and
+    #   +ractor_safe:+. For the store-backed path, wrap the store with {Stores::XFetch}.
     # @return [void]
     # @raise [ArgumentError] if the method does not exist, or option values are invalid
     #
@@ -94,7 +100,7 @@ module SafeMemoize
     # @example With a custom store
     #   STORE = SafeMemoize::Stores::Memory.new
     #   memoize :fetch, store: STORE, ttl: 300
-    def memoize(method_name, ttl: UNSET, max_size: UNSET, ttl_refresh: UNSET, if: UNSET, unless: UNSET, shared: UNSET, key: UNSET, store: UNSET, fiber_local: UNSET, ractor_safe: UNSET, namespace: UNSET, shared_cache: UNSET, cache_bust: UNSET, copy_on_read: UNSET, group: UNSET, circuit_breaker: UNSET, **extension_options)
+    def memoize(method_name, ttl: UNSET, max_size: UNSET, ttl_refresh: UNSET, if: UNSET, unless: UNSET, shared: UNSET, key: UNSET, store: UNSET, fiber_local: UNSET, ractor_safe: UNSET, namespace: UNSET, shared_cache: UNSET, cache_bust: UNSET, copy_on_read: UNSET, group: UNSET, circuit_breaker: UNSET, stampede_protection: UNSET, **extension_options)
       method_name = method_name.to_sym
 
       unless method_defined?(method_name) || private_method_defined?(method_name) || protected_method_defined?(method_name)
@@ -138,6 +144,7 @@ module SafeMemoize
         store = cls_defaults[:store] if store.equal?(UNSET) && cls_defaults.key?(:store)
         group = cls_defaults[:group] if group.equal?(UNSET) && cls_defaults.key?(:group)
         circuit_breaker = cls_defaults[:circuit_breaker] if circuit_breaker.equal?(UNSET) && cls_defaults.key?(:circuit_breaker)
+        stampede_protection = cls_defaults[:stampede_protection] if stampede_protection.equal?(UNSET) && cls_defaults.key?(:stampede_protection)
       end
 
       # Normalize remaining UNSET to original per-call defaults
@@ -155,6 +162,7 @@ module SafeMemoize
       copy_on_read = false if copy_on_read.equal?(UNSET)
       group = nil if group.equal?(UNSET)
       circuit_breaker = nil if circuit_breaker.equal?(UNSET)
+      stampede_protection = nil if stampede_protection.equal?(UNSET)
       cond_if = nil if cond_if.equal?(UNSET)
       cond_unless = nil if cond_unless.equal?(UNSET)
 
@@ -199,6 +207,24 @@ module SafeMemoize
         raise ArgumentError, "cache_bust: and key: cannot be combined" if key
       end
 
+      if store.is_a?(Array)
+        store.each_with_index do |s, i|
+          unless s.is_a?(SafeMemoize::Stores::Base)
+            raise ArgumentError, "store: Array entry [#{i}] must be a Stores::Base instance (got #{s.class})"
+          end
+        end
+        store = SafeMemoize::Stores::Multilevel.new(*store)
+      end
+
+      if stampede_protection
+        unless stampede_protection == true || stampede_protection.is_a?(Numeric)
+          raise ArgumentError, "stampede_protection: must be true or a Numeric beta value (got #{stampede_protection.class})"
+        end
+        raise ArgumentError, "stampede_protection: requires ttl: to be set" if ttl.nil?
+        raise ArgumentError, "stampede_protection: is incompatible with store: — use Stores::XFetch instead" if store
+        raise ArgumentError, "stampede_protection: is incompatible with ractor_safe:" if ractor_safe
+      end
+
       if store
         raise ArgumentError, "store: must be a SafeMemoize::Stores::Base instance (got #{store.class})" unless store.is_a?(SafeMemoize::Stores::Base)
         raise ArgumentError, "max_size: is not supported with store: — use the store adapter's own eviction" if max_size
@@ -354,7 +380,15 @@ module SafeMemoize
             fiber_cache = fiber_memo_cache!
             record = fiber_cache[cache_key]
 
-            if memo_record_live?(record)
+            sp_early = stampede_protection && memo_record_live?(record) && record[:expires_at] &&
+              (record[:delta].to_f > 0) &&
+              begin
+                sp_beta = stampede_protection.is_a?(Numeric) ? stampede_protection.to_f : 1.0
+                now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+                now - record[:delta].to_f * sp_beta * Math.log(rand) >= record[:expires_at]
+              end
+
+            if memo_record_live?(record) && !sp_early
               if max_size
                 lru = fiber_memo_lru![method_name] ||= {}
                 lru.delete(cache_key)
@@ -365,7 +399,7 @@ module SafeMemoize
               call_memo_hooks(:on_hit, cache_key, record)
               dup_fn.call(memo_record_value(record))
             else
-              call_memo_hooks(:on_expire, cache_key, record) if record
+              call_memo_hooks(:on_expire, cache_key, record) if record && (!memo_record_live?(record) || sp_early)
 
               start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
               value = Adapters::OpenTelemetry.trace(
@@ -373,7 +407,7 @@ module SafeMemoize
               ) { super(*args, **kwargs) }
               elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
-              new_record = memo_record(value, expires_at: memo_expires_at(ttl))
+              new_record = memo_record(value, expires_at: memo_expires_at(ttl), delta: stampede_protection ? elapsed_time : nil)
 
               if !condition || condition.call(value)
                 if max_size
@@ -432,7 +466,14 @@ module SafeMemoize
               now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
               record_live = record && (record[:expires_at].nil? || record[:expires_at] > now)
 
-              if record_live
+              sp_early = record_live && stampede_protection && record[:expires_at] &&
+                (record[:delta].to_f > 0) &&
+                begin
+                  sp_beta = stampede_protection.is_a?(Numeric) ? stampede_protection.to_f : 1.0
+                  now - record[:delta].to_f * sp_beta * Math.log(rand) >= record[:expires_at]
+                end
+
+              if record_live && !sp_early
                 if max_size
                   lru = klass.send(:__safe_memo_shared_lru_order__)[method_name] ||= {}
                   lru.delete(cache_key)
@@ -443,13 +484,13 @@ module SafeMemoize
                 call_memo_hooks(:on_hit, cache_key, record)
                 dup_fn.call(record[:value])
               else
-                call_memo_hooks(:on_expire, cache_key, record) if record && !record_live
+                call_memo_hooks(:on_expire, cache_key, record) if record && (!record_live || sp_early)
 
                 start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
                 value = Adapters::OpenTelemetry.trace(SafeMemoize.configuration.opentelemetry_tracer, method_name, klass.name) { super(*args, **kwargs) }
                 elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
-                new_record = memo_record(value, expires_at: memo_expires_at(ttl))
+                new_record = memo_record(value, expires_at: memo_expires_at(ttl), delta: stampede_protection ? elapsed_time : nil)
 
                 if !condition || condition.call(value)
                   if max_size
@@ -493,10 +534,22 @@ module SafeMemoize
 
           cache_key = compute_cache_key(method_name, args, kwargs)
 
-          if max_size || condition || ttl_refresh
-            # Locked path: used when LRU tracking, conditional storage, or TTL refresh is needed.
+          if max_size || condition || ttl_refresh || stampede_protection
+            # Locked path: LRU, conditional storage, TTL refresh, or stampede protection.
+            sp_beta = stampede_protection.is_a?(Numeric) ? stampede_protection.to_f : 1.0
+
             memo_mutex!.synchronize do
               record = memo_cache_record(cache_key)
+
+              if record && stampede_protection && record[:expires_at]
+                now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+                delta = record[:delta].to_f
+                if delta > 0 && now - delta * sp_beta * Math.log(rand) >= record[:expires_at]
+                  call_memo_hooks(:on_expire, cache_key, record)
+                  record = nil
+                end
+              end
+
               if record
                 lru_touch(method_name, cache_key) if max_size
                 record[:expires_at] = memo_expires_at(ttl) if ttl_refresh
@@ -508,7 +561,7 @@ module SafeMemoize
                 value = Adapters::OpenTelemetry.trace(SafeMemoize.configuration.opentelemetry_tracer, method_name, self.class.name) { super(*args, **kwargs) }
                 elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
-                new_record = memo_record(value, expires_at: memo_expires_at(ttl))
+                new_record = memo_record(value, expires_at: memo_expires_at(ttl), delta: stampede_protection ? elapsed_time : nil)
                 if !condition || condition.call(value)
                   lru_evict_if_over_limit(method_name, max_size) if max_size
                   @__safe_memo_cache__ ||= {}
@@ -905,9 +958,7 @@ module SafeMemoize
 
             cache_key = Ractor.make_shareable([method_name, deep_freeze_copy(args), deep_freeze_copy(kwargs)])
 
-            tag = Thread.current.object_id
-            supervisor.send(Ractor.make_shareable([Ractor.current, tag, :fetch, cache_key]))
-            response = Ractor.receive_if { |m| m.is_a?(Array) && m[0] == tag }[1]
+            response = RactorSharedMethods.round_trip(supervisor, :fetch, cache_key)
 
             if response[:hit]
               record_cache_hit(cache_key)
@@ -932,8 +983,7 @@ module SafeMemoize
               cached_at: now
             })
 
-            supervisor.send(Ractor.make_shareable([Ractor.current, tag, :store, cache_key, record]))
-            stored = Ractor.receive_if { |m| m.is_a?(Array) && m[0] == tag }[1]
+            stored = RactorSharedMethods.round_trip(supervisor, :store, cache_key, record)
             stored_record = stored[:stored]
 
             record_cache_miss(cache_key, elapsed_time)

data/lib/safe_memoize/ractor_shared_methods.rb

@@ -15,9 +15,65 @@ module SafeMemoize
   # - +if:+, +unless:+, +max_size:+, +ttl_refresh:+, +key:+, and +store:+ are
   #   incompatible and raise +ArgumentError+ at +memoize+ time.
   # - When calling a ractor-safe memoized method from the main Ractor with multiple
-  #   threads, responses are matched by thread identity so concurrent callers do not
-  #   consume each other's replies.
+  #   threads, responses are matched by thread identity and each send/receive pair
+  #   is serialized per Ractor, so concurrent callers do not consume each other's
+  #   replies or lose a wakeup.
   module RactorSharedMethods
+    MUTEX_KEY = :__safe_memo_ractor_mutex__
+
+    # Ruby 4.0 replaced +Ractor.receive_if+ with +Ractor::Port+.
+    PORTS = defined?(Ractor::Port) ? true : false
+
+    # Sends a request to +supervisor+ and blocks until its reply arrives,
+    # returning the reply payload.
+    def self.round_trip(supervisor, op, *args)
+      # :nocov:
+      return round_trip_via_port(supervisor, op, *args) if PORTS
+      # :nocov:
+
+      round_trip_via_queue(supervisor, op, *args)
+    end
+
+    # Ruby 4.0+: each call gets its own port, so callers never share a queue.
+    # :nocov:
+    def self.round_trip_via_port(supervisor, op, *args)
+      port = Ractor::Port.new
+      supervisor.send(Ractor.make_shareable([port, Thread.current.object_id, op, *args]))
+      port.receive[1]
+    ensure
+      port&.close
+    end
+    # :nocov:
+
+    # Ruby 3.x: replies are matched by thread identity, but every thread in a
+    # Ractor waits on that Ractor's single incoming queue. Ruby 3.x can lose a
+    # wakeup when several threads sit in +Ractor.receive_if+ at once, leaving one
+    # waiting forever, so the send/receive pair is serialized per Ractor. The
+    # supervisor handles requests one at a time anyway, so this costs no
+    # throughput.
+    def self.round_trip_via_queue(supervisor, op, *args)
+      tag = Thread.current.object_id
+      msg = Ractor.make_shareable([Ractor.current, tag, op, *args])
+
+      ractor_mutex.synchronize do
+        supervisor.send(msg)
+        Ractor.receive_if { |m| m.is_a?(Array) && m[0] == tag }[1]
+      end
+    end
+
+    # Per-Ractor mutex held in Ractor-local storage (a plain +Mutex+ constant is
+    # not Ractor-shareable).
+    def self.ractor_mutex
+      Ractor.current[MUTEX_KEY] ||
+        if Ractor.respond_to?(:store_if_absent)
+          Ractor.store_if_absent(MUTEX_KEY) { Mutex.new }
+        else
+          # :nocov:
+          Ractor.current[MUTEX_KEY] ||= Mutex.new # Ruby 3.3 lacks store_if_absent
+          # :nocov:
+        end
+    end
+
     # Clears one or all entries from the Ractor-safe shared cache.
     #
     # @param method_name [Symbol, String]
@@ -76,13 +132,8 @@ module SafeMemoize
     private
 
     # Sends a message to the supervisor and blocks until the tagged response arrives.
-    # Uses Thread.current.object_id as a per-call tag so concurrent threads in the
-    # main Ractor do not steal each other's replies.
     def __ractor_cache_send__(supervisor, op, *args)
-      tag = Thread.current.object_id
-      msg = Ractor.make_shareable([Ractor.current, tag, op, *args])
-      supervisor.send(msg)
-      Ractor.receive_if { |m| m.is_a?(Array) && m[0] == tag }[1]
+      RactorSharedMethods.round_trip(supervisor, op, *args)
     end
 
     # Creates the supervisor Ractor that owns this class's Ractor-safe shared cache.

data/lib/safe_memoize/release_tooling.rb

@@ -10,6 +10,7 @@ module SafeMemoize
     VERSION_PATTERN = /VERSION = "[^"]+"/
     SEMVER_PATTERN = /\A\d+\.\d+\.\d+(?:[-.][0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?\z/
     UNRELEASED_HEADING = "## [Unreleased]"
+    UNRELEASED_LINK = %r{^\[Unreleased\]: (?<base>\S+)/compare/v(?<previous>[^.\s]\S*?)\.\.\.HEAD$}
 
     def normalize_version(version)
       normalized_version = version.to_s.sub(/\Av/, "")
@@ -43,7 +44,24 @@ module SafeMemoize
         raise ArgumentError, "CHANGELOG.md already contains #{normalized_version}"
       end
 
-      contents.sub(UNRELEASED_HEADING, "#{UNRELEASED_HEADING}\n\n#{release_heading}")
+      contents = contents.sub(UNRELEASED_HEADING, "#{UNRELEASED_HEADING}\n\n#{release_heading}")
+      update_version_links(contents, normalized_version)
+    end
+
+    # Keeps the reference-style link definitions at the bottom of the CHANGELOG
+    # in sync: points [Unreleased] at the new tag and adds a compare link for
+    # the new version. Left untouched when no [Unreleased] link is present.
+    def update_version_links(contents, version)
+      match = contents.match(UNRELEASED_LINK)
+      return contents unless match
+
+      base = match[:base]
+      replacement = [
+        "[Unreleased]: #{base}/compare/v#{version}...HEAD",
+        "[#{version}]: #{base}/compare/v#{match[:previous]}...v#{version}"
+      ].join("\n")
+
+      contents.sub(UNRELEASED_LINK) { replacement }
     end
 
     # Removes milestone sections from ROADMAP.md where every feature row has

data/lib/safe_memoize/stores/multilevel.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Stores
+    # Multi-level (L1/L2/…) cache store that checks faster layers first and
+    # promotes values up on a miss, reducing latency and load on slower backends.
+    #
+    # Reads walk the store list from first (fastest) to last (slowest). On a
+    # miss at level N the value is read from level N+1 and written back into
+    # all preceding levels ("read-through promotion"). Writes always go to every
+    # level so all layers stay consistent.
+    #
+    # @example In-process L1 + Redis L2
+    #   l1 = SafeMemoize::Stores::Memory.new
+    #   l2 = MyRedisStore.new
+    #
+    #   memoize :fetch, store: SafeMemoize::Stores::Multilevel.new(l1, l2)
+    #
+    # @example Via the store: Array shorthand
+    #   memoize :fetch, store: [l1, l2], ttl: 300
+    #
+    # @example With a short promote_expires_in for the L1 layer
+    #   memoize :fetch, store: SafeMemoize::Stores::Multilevel.new(l1, l2, promote_expires_in: 60)
+    class Multilevel < Base
+      # @return [Array<Stores::Base>] the ordered store layers (fastest first)
+      attr_reader :stores
+
+      # @param stores [Array<Stores::Base>] two or more store instances, ordered
+      #   from fastest (L1) to slowest (last)
+      # @param promote_expires_in [Numeric, nil] TTL applied when promoting a
+      #   value from a deeper layer into a shallower one; +nil+ means no expiry
+      #   on the promoted entry (the L1 store's own eviction — e.g. LRU — handles
+      #   memory bounds instead)
+      # @raise [ArgumentError] if fewer than two stores are supplied, or any
+      #   element is not a {Stores::Base} instance
+      def initialize(*stores, promote_expires_in: nil)
+        raise ArgumentError, "Multilevel requires at least 2 stores" if stores.size < 2
+
+        stores.each_with_index do |s, i|
+          unless s.is_a?(Base)
+            raise ArgumentError,
+              "Multilevel store[#{i}] must be a Stores::Base instance (got #{s.class})"
+          end
+        end
+
+        @stores = stores.freeze
+        @promote_expires_in = promote_expires_in ? Float(promote_expires_in) : nil
+      end
+
+      # Walk levels from fastest to slowest; return the first hit, promoting
+      # the value into all shallower layers.
+      def read(key)
+        @stores.each_with_index do |store, i|
+          result = store.read(key)
+          next if result.equal?(MISS)
+
+          # Promote into every shallower level
+          @stores.first(i).each { |s| s.write(key, result, expires_in: @promote_expires_in) }
+          return result
+        end
+
+        MISS
+      end
+
+      # Write to every level simultaneously.
+      def write(key, value, expires_in: nil)
+        @stores.each { |s| s.write(key, value, expires_in: expires_in) }
+      end
+
+      # Delete from every level.
+      def delete(key)
+        @stores.each { |s| s.delete(key) }
+      end
+
+      # Clear every level.
+      def clear
+        @stores.each(&:clear)
+      end
+
+      # Union of live keys across all levels.
+      def keys
+        @stores.flat_map(&:keys).uniq
+      end
+    end
+  end
+end

data/lib/safe_memoize/stores/xfetch.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Stores
+    # Wraps any {Base} store adapter with probabilistic early expiry (the
+    # XFetch algorithm) to prevent cache stampedes — the thundering-herd
+    # problem where many processes simultaneously recompute a value the moment
+    # it expires under high load.
+    #
+    # Instead of waiting until {#read} returns {MISS} at the hard expiry
+    # deadline, the wrapper stochastically returns {MISS} slightly before
+    # expiry, giving one process a head start on recomputation while everyone
+    # else still gets the cached value. The probability of early expiry rises
+    # as the entry approaches its deadline.
+    #
+    # === XFetch formula
+    #
+    #   early_expire = now − (delta × beta × log(rand)) ≥ expires_at
+    #
+    # * +delta+ — estimated computation time in seconds (default 0.1 s).
+    #   Configure this to the typical duration of the underlying computation.
+    # * +beta+  — aggressiveness scalar (default 1.0); higher values trigger
+    #   early recomputation more eagerly.
+    #
+    # Values are stored internally as an envelope +{value:, expires_at:}+ so
+    # the wrapper always knows the hard deadline regardless of what the inner
+    # store exposes on read. The envelope survives standard Ruby Marshal
+    # serialization (Redis via the +redis-store+ or +redis-client+ gems,
+    # Rails.cache, etc.). Values that cannot be serialized alongside a small
+    # hash are not supported.
+    #
+    # @example Wrap a Redis store
+    #   store = SafeMemoize::Stores::XFetch.new(
+    #     MyRedisStore.new,
+    #     delta: 0.2,   # typical computation time in seconds
+    #     beta:  1.5    # slightly aggressive early expiry
+    #   )
+    #   memoize :fetch, store: store, ttl: 300
+    #
+    # @example Compose with CircuitBreaker
+    #   store = SafeMemoize::Stores::XFetch.new(
+    #     SafeMemoize::Stores::CircuitBreaker.new(MyRedisStore.new),
+    #     delta: 0.1
+    #   )
+    #   memoize :fetch, store: store, ttl: 60
+    class XFetch < Base
+      ENVELOPE_KEY = :__sm_xfetch_v1__
+
+      DEFAULT_BETA = 1.0
+      DEFAULT_DELTA = 0.1
+
+      # @return [Stores::Base] the wrapped inner store
+      attr_reader :wrapped_store
+      # @return [Float] aggressiveness scalar
+      attr_reader :beta
+      # @return [Float] estimated computation time in seconds
+      attr_reader :delta
+
+      # @param store [Stores::Base] the backing store to wrap
+      # @param beta  [Numeric] aggressiveness scalar (default 1.0)
+      # @param delta [Numeric] estimated computation time in seconds (default 0.1)
+      # @raise [ArgumentError] if +store+ is not a {Stores::Base} instance, or
+      #   if +beta+/+delta+ are not positive numbers
+      def initialize(store, beta: DEFAULT_BETA, delta: DEFAULT_DELTA)
+        unless store.is_a?(Base)
+          raise ArgumentError, "XFetch requires a Stores::Base instance (got #{store.class})"
+        end
+
+        @wrapped_store = store
+        @beta = Float(beta)
+        @delta = Float(delta)
+
+        raise ArgumentError, "beta must be positive" unless @beta > 0
+        raise ArgumentError, "delta must be positive" unless @delta > 0
+      end
+
+      # Read from the wrapped store and apply the XFetch probabilistic check.
+      #
+      # Returns {MISS} when:
+      # * the inner store has no entry for +key+
+      # * the stored value is not an XFetch envelope (possibly written by an
+      #   older version or a different store wrapper)
+      # * the XFetch formula triggers early expiry
+      def read(key)
+        raw = @wrapped_store.read(key)
+        return MISS if raw.equal?(MISS)
+        return MISS unless envelope?(raw)
+
+        expires_at = raw[:expires_at]
+
+        if expires_at
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          early = now - @delta * @beta * Math.log(rand) >= expires_at
+          return MISS if early
+        end
+
+        raw[:value]
+      end
+
+      # Write the value to the wrapped store inside an XFetch envelope.
+      def write(key, value, expires_in: nil)
+        expires_at = expires_in ? Process.clock_gettime(Process::CLOCK_MONOTONIC) + expires_in.to_f : nil
+        envelope = {ENVELOPE_KEY => true, :value => value, :expires_at => expires_at}
+        @wrapped_store.write(key, envelope, expires_in: expires_in)
+      end
+
+      # Delete from the wrapped store.
+      def delete(key)
+        @wrapped_store.delete(key)
+      end
+
+      # Clear the wrapped store.
+      def clear
+        @wrapped_store.clear
+      end
+
+      # Returns live keys from the wrapped store.
+      def keys
+        @wrapped_store.keys
+      end
+
+      private
+
+      def envelope?(value)
+        value.is_a?(Hash) && value[ENVELOPE_KEY]
+      end
+    end
+  end
+end

data/lib/safe_memoize/version.rb

@@ -2,5 +2,5 @@
 
 module SafeMemoize
   # The current gem version string.
-  VERSION = "1.6.0"
+  VERSION = "1.7.1"
 end

data/lib/safe_memoize.rb

@@ -6,6 +6,8 @@ require_relative "safe_memoize/extension"
 require_relative "safe_memoize/stores/base"
 require_relative "safe_memoize/stores/memory"
 require_relative "safe_memoize/stores/circuit_breaker"
+require_relative "safe_memoize/stores/multilevel"
+require_relative "safe_memoize/stores/xfetch"
 require_relative "safe_memoize/adapters/statsd"
 require_relative "safe_memoize/adapters/opentelemetry"
 require_relative "safe_memoize/adapters/concurrent_ruby"