safe_memoize 1.1.0 → 1.3.0

data/lib/safe_memoize/class_methods.rb

@@ -29,6 +29,36 @@ module SafeMemoize
     #   {Stores::Base} subclass instance. The store is shared across all instances of the
     #   class. When +nil+, the default per-instance in-process hash is used.
     #   Cannot be combined with +max_size:+ or +shared:+.
+    # @param fiber_local [Boolean] when +true+, results are stored in
+    #   +Fiber[:__safe_memoize__]+ rather than instance variables. Each fiber gets its
+    #   own isolated cache that is automatically discarded when the fiber terminates. No
+    #   mutex is acquired. Cannot be combined with +shared:+ or +store:+.
+    # @param ractor_safe [Boolean] when +true+, the class-level shared cache is owned by
+    #   a supervisor +Ractor+ rather than a +Mutex+-protected ivar, making it accessible
+    #   from worker Ractors. Requires +shared: true+. Cached values are deep-frozen via
+    #   +Ractor.make_shareable+. Incompatible with +if:+, +unless:+, +max_size:+,
+    #   +ttl_refresh:+, +key:+, and +store:+.
+    # @param namespace [String, nil] prefix prepended to every cache key for this method,
+    #   scoping it to a logical partition. Takes precedence over both the class-level
+    #   {#safe_memoize_namespace} and the global {SafeMemoize::Configuration#namespace}.
+    #   Useful for versioning a single method independently of its peers. Must not contain
+    #   the character +:+.
+    # @param cache_bust [Proc, Symbol, nil] callable invoked on the instance (via
+    #   +instance_exec+) on every cache lookup to obtain a version token. The token is
+    #   folded into the cache key alongside the normal arguments, so when the token
+    #   changes (e.g. an ActiveRecord +updated_at+ timestamp advances after a +save+)
+    #   the old key no longer matches any entry — the method is recomputed and the result
+    #   stored under the new key. Accepts any callable (+Proc+, +lambda+, +Method+) that
+    #   takes no arguments, or a +Symbol+ naming an instance method. Cannot be combined
+    #   with +key:+.
+    # @param shared_cache [String, nil] name of a globally-registered shared cache store
+    #   (see {SafeMemoize.shared_cache} and {SafeMemoize.register_shared_cache}). All
+    #   instances of any class that memoizes a method with the same +shared_cache:+ name
+    #   read and write the same backing store, enabling cross-class cache sharing.
+    #   The store is resolved at +memoize+ definition time; call
+    #   {SafeMemoize.register_shared_cache} before the class is loaded to supply a custom
+    #   adapter. Incompatible with +shared:+, +store:+, +fiber_local:+, +ractor_safe:+,
+    #   and +max_size:+. Composes naturally with +namespace:+, +ttl:+, +if:+, and +key:+.
     # @return [void]
     # @raise [ArgumentError] if the method does not exist, or option values are invalid
     #
@@ -46,13 +76,32 @@ module SafeMemoize
     # @example With a custom store
     #   STORE = SafeMemoize::Stores::Memory.new
     #   memoize :fetch, store: STORE, ttl: 300
-    def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil, store: nil)
+    def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil, store: nil, fiber_local: false, ractor_safe: false, namespace: nil, shared_cache: nil, cache_bust: nil, **extension_options)
       method_name = method_name.to_sym
 
       unless method_defined?(method_name) || private_method_defined?(method_name) || protected_method_defined?(method_name)
         raise ArgumentError, "cannot memoize :#{method_name} — no instance method with that name is defined on #{self}"
       end
 
+      unless extension_options.empty?
+        extension_options.each_key do |opt|
+          raise ArgumentError, "unknown memoize option :#{opt} — no registered extension handles it" unless SafeMemoize.extension_for_option(opt)
+        end
+
+        injected = {}
+        extension_options.each do |opt, val|
+          result = SafeMemoize.extension_for_option(opt).process_memoize_option(opt, val, method_name, extension_options)
+          injected.merge!(result)
+        end
+
+        ttl = injected[:ttl] if injected.key?(:ttl)
+        max_size = injected[:max_size] if injected.key?(:max_size)
+        namespace = injected[:namespace] if injected.key?(:namespace)
+        store = injected[:store] if injected.key?(:store)
+        shared_cache = injected[:shared_cache] if injected.key?(:shared_cache)
+        cache_bust = injected[:cache_bust] if injected.key?(:cache_bust)
+      end
+
       visibility = memoized_method_visibility(method_name)
 
       config = SafeMemoize.configuration
@@ -93,27 +142,73 @@ module SafeMemoize
       raise ArgumentError, ":unless must be callable" if cond_unless && !cond_unless.respond_to?(:call)
       raise ArgumentError, ":key must be callable" if key && !key.respond_to?(:call)
 
+      if cache_bust
+        unless cache_bust.respond_to?(:call) || cache_bust.is_a?(Symbol)
+          raise ArgumentError, "cache_bust: must be a callable or Symbol (got #{cache_bust.class})"
+        end
+        raise ArgumentError, "cache_bust: and key: cannot be combined" if key
+      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
         raise ArgumentError, "shared: and store: cannot be combined" if shared
       end
 
-      # Resolve effective store: explicit store: wins; global default applies when
-      # compatible (max_size: and shared: are incompatible — fall back silently).
+      if fiber_local
+        raise ArgumentError, "fiber_local: and shared: cannot be combined" if shared
+        raise ArgumentError, "fiber_local: and store: cannot be combined" if store
+      end
+
+      if ractor_safe
+        raise ArgumentError, "ractor_safe: requires shared: true" unless shared
+        raise ArgumentError, "ractor_safe: is incompatible with if:/unless:" if cond_if || cond_unless
+        raise ArgumentError, "ractor_safe: is incompatible with max_size:" if max_size
+        raise ArgumentError, "ractor_safe: is incompatible with ttl_refresh:" if ttl_refresh
+        raise ArgumentError, "ractor_safe: is incompatible with key:" if key
+        raise ArgumentError, "ractor_safe: is incompatible with store:" if store
+      end
+
+      if namespace
+        raise ArgumentError, "namespace: must be a String (got #{namespace.class})" unless namespace.is_a?(String)
+        raise ArgumentError, "namespace: must not be empty" if namespace.empty?
+        raise ArgumentError, "namespace: must not contain ':'" if namespace.include?(":")
+        __safe_memo_method_namespaces__[method_name] = namespace
+      end
+
+      if shared_cache
+        raise ArgumentError, "shared_cache: must be a String (got #{shared_cache.class})" unless shared_cache.is_a?(String)
+        raise ArgumentError, "shared_cache: must not be empty" if shared_cache.empty?
+        raise ArgumentError, "shared_cache: and shared: cannot be combined" if shared
+        raise ArgumentError, "shared_cache: and store: cannot be combined" if store
+        raise ArgumentError, "shared_cache: and fiber_local: cannot be combined" if fiber_local
+        raise ArgumentError, "shared_cache: and ractor_safe: cannot be combined" if ractor_safe
+        raise ArgumentError, "max_size: is not supported with shared_cache: — use the store adapter's own eviction" if max_size
+        store = SafeMemoize.shared_cache(shared_cache)
+      end
+
+      # Resolve effective store: per-method store: wins; then class-level
+      # safe_memoize_store; then global default_store. max_size: and shared:
+      # are incompatible with external stores — fall back silently.
       effective_store = store
       if effective_store.nil? && !max_size && !shared
-        global_default = SafeMemoize.configuration.default_store
-        if global_default
-          unless global_default.is_a?(SafeMemoize::Stores::Base)
-            raise ArgumentError,
-              "SafeMemoize.configuration.default_store must be a Stores::Base instance (got #{global_default.class})"
+        class_store = safe_memoize_store
+        if class_store
+          effective_store = class_store
+        else
+          global_default = SafeMemoize.configuration.default_store
+          if global_default
+            unless global_default.is_a?(SafeMemoize::Stores::Base)
+              raise ArgumentError,
+                "SafeMemoize.configuration.default_store must be a Stores::Base instance (got #{global_default.class})"
+            end
+            effective_store = global_default
           end
-          effective_store = global_default
         end
       end
 
       __safe_memo_class_key_generators__[method_name] = key if key
+      __safe_memo_class_cache_bust_generators__[method_name] = cache_bust if cache_bust
 
       # Normalize to a single "should cache?" predicate
       condition = if cond_if
@@ -134,7 +229,7 @@ module SafeMemoize
 
             unless cached.equal?(miss)
               effective_store.write(cache_key, cached, expires_in: ttl) if ttl_refresh
-              record_cache_hit(method_name, args, kwargs)
+              record_cache_hit(cache_key)
               call_memo_hooks(:on_hit, cache_key, {value: cached, expires_at: nil, cached_at: nil})
               return cached
             end
@@ -151,7 +246,7 @@ module SafeMemoize
               call_memo_hooks(:on_store, cache_key, {value: value, expires_at: nil, cached_at: now})
             end
 
-            record_cache_miss(method_name, args, kwargs, elapsed_time)
+            record_cache_miss(cache_key, elapsed_time)
             call_memo_hooks(:on_miss, cache_key, {value: value, expires_at: nil, cached_at: now})
 
             value
@@ -165,6 +260,77 @@ module SafeMemoize
         return
       end
 
+      if fiber_local
+        mod = Module.new do
+          define_method(method_name) do |*args, **kwargs, &block|
+            return super(*args, **kwargs, &block) if block
+
+            cache_key = compute_cache_key(method_name, args, kwargs)
+            fiber_cache = fiber_memo_cache!
+            record = fiber_cache[cache_key]
+
+            if memo_record_live?(record)
+              if max_size
+                lru = fiber_memo_lru![method_name] ||= {}
+                lru.delete(cache_key)
+                lru[cache_key] = true
+              end
+              record[:expires_at] = memo_expires_at(ttl) if ttl_refresh
+              record_cache_hit(cache_key)
+              call_memo_hooks(:on_hit, cache_key, record)
+              memo_record_value(record)
+            else
+              call_memo_hooks(:on_expire, cache_key, record) if record
+
+              start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+              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))
+
+              if !condition || condition.call(value)
+                if max_size
+                  lru = fiber_memo_lru![method_name] ||= {}
+                  if lru.size >= max_size
+                    evict_key = lru.keys.first
+                    lru.delete(evict_key)
+                    evicted = fiber_cache.delete(evict_key)
+                    call_memo_hooks(:on_evict, evict_key, evicted) if evicted
+                  end
+                end
+                fiber_cache[cache_key] = new_record
+                if max_size
+                  lru = fiber_memo_lru![method_name] ||= {}
+                  lru.delete(cache_key)
+                  lru[cache_key] = true
+                end
+                call_memo_hooks(:on_store, cache_key, new_record)
+              end
+
+              record_cache_miss(cache_key, elapsed_time)
+              call_memo_hooks(:on_miss, cache_key, new_record)
+
+              value
+            end
+          end
+
+          send(visibility, method_name)
+        end
+
+        prepend mod
+
+        return
+      end
+
+      if ractor_safe
+        extend(RactorSharedMethods) unless is_a?(RactorSharedMethods)
+        supervisor = __safe_memo_ractor_supervisor__
+        __memoize_ractor_safe__(method_name, ttl, visibility, supervisor)
+        return
+      end
+
       if shared
         klass = self
         shared_mutex = klass.send(:__safe_memo_shared_mutex__)
@@ -188,7 +354,7 @@ module SafeMemoize
                   lru[cache_key] = true
                 end
                 record[:expires_at] = memo_expires_at(ttl) if ttl_refresh
-                record_cache_hit(method_name, args, kwargs)
+                record_cache_hit(cache_key)
                 call_memo_hooks(:on_hit, cache_key, record)
                 record[:value]
               else
@@ -219,7 +385,7 @@ module SafeMemoize
                   call_memo_hooks(:on_store, cache_key, new_record)
                 end
 
-                record_cache_miss(method_name, args, kwargs, elapsed_time)
+                record_cache_miss(cache_key, elapsed_time)
                 call_memo_hooks(:on_miss, cache_key, new_record)
 
                 value
@@ -249,7 +415,7 @@ module SafeMemoize
               if record
                 lru_touch(method_name, cache_key) if max_size
                 record[:expires_at] = memo_expires_at(ttl) if ttl_refresh
-                record_cache_hit(method_name, args, kwargs)
+                record_cache_hit(cache_key)
                 call_memo_hooks(:on_hit, cache_key, record)
                 memo_record_value(record)
               else
@@ -265,7 +431,7 @@ module SafeMemoize
                   lru_touch(method_name, cache_key) if max_size
                   call_memo_hooks(:on_store, cache_key, new_record)
                 end
-                record_cache_miss(method_name, args, kwargs, elapsed_time)
+                record_cache_miss(cache_key, elapsed_time)
                 call_memo_hooks(:on_miss, cache_key, new_record)
 
                 value
@@ -274,7 +440,7 @@ module SafeMemoize
           else
             # Fast path: check without lock
             if (record = memo_cache_record(cache_key))
-              record_cache_hit(method_name, args, kwargs)
+              record_cache_hit(cache_key)
               call_memo_hooks(:on_hit, cache_key, record)
               return memo_record_value(record)
             end
@@ -287,7 +453,7 @@ module SafeMemoize
             elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
             with_memo_lock do
-              record_cache_miss(method_name, args, kwargs, elapsed_time)
+              record_cache_miss(cache_key, elapsed_time)
               new_record = memo_cache_record(cache_key)
               call_memo_hooks(:on_store, cache_key, new_record)
               call_memo_hooks(:on_miss, cache_key, new_record)
@@ -303,6 +469,57 @@ module SafeMemoize
       prepend mod
     end
 
+    # Returns the class-level default cache store, or +nil+ if not set.
+    #
+    # Set this to any {Stores::Base} instance to route every +memoize+ call on
+    # this class through that store, without needing to pass +store:+ to each
+    # individual +memoize+ call.  A per-method +store:+ option still takes
+    # precedence, and the global {SafeMemoize::Configuration#default_store} is
+    # the final fallback.
+    #
+    # @return [Stores::Base, nil]
+    def safe_memoize_store
+      @__safe_memoize_store__
+    end
+
+    # Sets the class-level default cache store.
+    #
+    # @param store [Stores::Base, nil] a store instance, or +nil+ to clear
+    # @return [Stores::Base, nil]
+    # @raise [ArgumentError] if +store+ is not a {Stores::Base} instance (and not +nil+)
+    def safe_memoize_store=(store)
+      if store && !store.is_a?(SafeMemoize::Stores::Base)
+        raise ArgumentError,
+          "safe_memoize_store= must be a SafeMemoize::Stores::Base instance (got #{store.class})"
+      end
+      @__safe_memoize_store__ = store
+    end
+
+    # Returns the class-level namespace prefix, or +nil+ if not set.
+    #
+    # When set, this prefix is prepended to every cache key produced by +memoize+
+    # calls on this class that do not specify their own +namespace:+ option.
+    # The global {SafeMemoize::Configuration#namespace} is the final fallback.
+    #
+    # @return [String, nil]
+    def safe_memoize_namespace
+      @__safe_memoize_namespace__
+    end
+
+    # Sets the class-level namespace prefix.
+    #
+    # @param ns [String, nil] a non-empty string without +:+, or +nil+ to clear
+    # @return [String, nil]
+    # @raise [ArgumentError] if +ns+ is not a valid namespace string
+    def safe_memoize_namespace=(ns)
+      if ns
+        raise ArgumentError, "safe_memoize_namespace= must be a String (got #{ns.class})" unless ns.is_a?(String)
+        raise ArgumentError, "safe_memoize_namespace= must not be empty" if ns.empty?
+        raise ArgumentError, "safe_memoize_namespace= must not contain ':'" if ns.include?(":")
+      end
+      @__safe_memoize_namespace__ = ns
+    end
+
     # Memoizes every eligible public instance method defined directly on the class.
     #
     # Accepts all options that {#memoize} accepts, plus +:except:+ and +:only:+.
@@ -344,14 +561,15 @@ module SafeMemoize
     # @return [void]
     def reset_shared_memo(method_name, *args, **kwargs)
       method_name = method_name.to_sym
-      specific_key = (args.empty? && kwargs.empty?) ? nil : [method_name, args, kwargs]
+      effective = __safe_memo_effective_key_name__(method_name)
+      specific_key = (args.empty? && kwargs.empty?) ? nil : [effective, args, kwargs]
 
       __safe_memo_shared_mutex__.synchronize do
         if specific_key
           __safe_memo_shared_cache__.delete(specific_key)
           __safe_memo_shared_lru_order__[method_name]&.delete(specific_key)
         else
-          __safe_memo_shared_cache__.delete_if { |key, _| key[0] == method_name }
+          __safe_memo_shared_cache__.delete_if { |key, _| key[0] == effective }
           __safe_memo_shared_lru_order__.delete(method_name)
         end
       end
@@ -374,7 +592,8 @@ module SafeMemoize
     # @return [Boolean]
     def shared_memoized?(method_name, *args, **kwargs)
       method_name = method_name.to_sym
-      cache_key = [method_name, args, kwargs]
+      effective = __safe_memo_effective_key_name__(method_name)
+      cache_key = [effective, args, kwargs]
 
       __safe_memo_shared_mutex__.synchronize do
         cache = @__safe_memo_shared_cache__
@@ -397,7 +616,12 @@ module SafeMemoize
         cache = @__safe_memo_shared_cache__ || {}
         now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         live = cache.reject { |_, r| r[:expires_at] && r[:expires_at] <= now }
-        method_name ? live.count { |key, _| key[0] == method_name.to_sym } : live.count
+        if method_name
+          effective = __safe_memo_effective_key_name__(method_name.to_sym)
+          live.count { |key, _| key[0] == effective }
+        else
+          live.count
+        end
       end
     end
 
@@ -410,7 +634,8 @@ module SafeMemoize
     # @return [Float, nil]
     def shared_memo_age(method_name, *args, **kwargs)
       method_name = method_name.to_sym
-      cache_key = [method_name, args, kwargs]
+      effective = __safe_memo_effective_key_name__(method_name)
+      cache_key = [effective, args, kwargs]
 
       __safe_memo_shared_mutex__.synchronize do
         cache = @__safe_memo_shared_cache__
@@ -437,7 +662,8 @@ module SafeMemoize
     # @return [Boolean]
     def shared_memo_stale?(method_name, *args, **kwargs)
       method_name = method_name.to_sym
-      cache_key = [method_name, args, kwargs]
+      effective = __safe_memo_effective_key_name__(method_name)
+      cache_key = [effective, args, kwargs]
 
       __safe_memo_shared_mutex__.synchronize do
         cache = @__safe_memo_shared_cache__
@@ -471,11 +697,92 @@ module SafeMemoize
       @__safe_memo_class_key_generators__ ||= {}
     end
 
+    def __safe_memo_method_namespaces__
+      @__safe_memo_method_namespaces__ ||= {}
+    end
+
+    def __safe_memo_class_cache_bust_generators__
+      @__safe_memo_class_cache_bust_generators__ ||= {}
+    end
+
+    # Resolves the effective first-element key sym for a given bare method name,
+    # applying the active namespace. Used by class-level cache operations where
+    # instance methods (compute_cache_key) are unavailable.
+    def __safe_memo_effective_key_name__(method_name)
+      ns_map = @__safe_memo_method_namespaces__
+      ns = (ns_map && ns_map[method_name]) ||
+        @__safe_memoize_namespace__ ||
+        SafeMemoize.configuration.namespace
+      ns ? :"#{ns}:#{method_name}" : method_name
+    end
+
     def memoized_method_visibility(method_name)
       return :private if private_method_defined?(method_name)
       return :protected if protected_method_defined?(method_name)
 
       :public
     end
+
+    # Builds and prepends the ractor_safe memoize wrapper in its own method so
+    # the Proc only closes over the four Ractor-shareable locals (method_name,
+    # ttl, visibility, supervisor) rather than the full memoize binding, which
+    # contains non-shareable objects like SafeMemoize.configuration.
+    #
+    # The Proc is created inside module_eval so its self is the anonymous
+    # module (a shareable object), then frozen via Ractor.make_shareable before
+    # being passed to define_method. Without that step, ANY define_method Proc
+    # is considered non-shareable by Ruby 3.x even when it captures nothing.
+    def __memoize_ractor_safe__(method_name, ttl, visibility, supervisor)
+      mod = Module.new
+      wrapper = mod.module_eval do
+        Ractor.make_shareable(
+          proc do |*args, **kwargs, &block|
+            return super(*args, **kwargs, &block) if block
+
+            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]
+
+            if response[:hit]
+              record_cache_hit(cache_key)
+              call_memo_hooks(:on_hit, cache_key, response[:record])
+              return response[:record][:value]
+            end
+
+            start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            value = super(*args, **kwargs)
+            elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+            begin
+              shareable_value = Ractor.make_shareable(value)
+            rescue => e
+              raise ArgumentError, "ractor_safe: memoized values must be Ractor-shareable (#{e.message})"
+            end
+
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            record = Ractor.make_shareable({
+              value: shareable_value,
+              expires_at: ttl ? now + ttl : nil,
+              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_record = stored[:stored]
+
+            record_cache_miss(cache_key, elapsed_time)
+            call_memo_hooks(:on_store, cache_key, stored_record)
+            call_memo_hooks(:on_miss, cache_key, stored_record)
+
+            stored_record[:value]
+          end
+        )
+      end
+      mod.define_method(method_name, wrapper)
+      mod.send(visibility, method_name)
+      prepend mod
+    end
   end
 end

data/lib/safe_memoize/configuration.rb

@@ -48,6 +48,13 @@ module SafeMemoize
     #   store and will silently continue using the per-instance hash even when this is set.
     attr_accessor :default_store
 
+    # @return [String, nil] Global namespace prefix applied to every cache key produced by
+    #   {ClassMethods#memoize}. Useful for versioned deployments (change the namespace to
+    #   bust all in-flight cached values) and multi-tenant setups (scope keys to a tenant
+    #   identifier). A class-level {ClassMethods#safe_memoize_namespace} or a per-method
+    #   +namespace:+ option takes precedence over this value. +nil+ means no prefix.
+    attr_accessor :namespace
+
     # @api private
     def initialize
       @default_ttl = nil
@@ -58,6 +65,7 @@ module SafeMemoize
       @statsd_client = nil
       @opentelemetry_tracer = nil
       @default_store = nil
+      @namespace = nil
     end
   end
 end

data/lib/safe_memoize/custom_key_methods.rb

@@ -19,14 +19,23 @@ module SafeMemoize
     def compute_cache_key(method_name, args, kwargs)
       method_name = method_name.to_sym
 
+      ns = __safe_memo_resolve_namespace__(method_name)
+      effective_name = ns ? :"#{ns}:#{method_name}" : method_name
+
       # Instance-level key generator takes priority over class-level
       key_block = custom_key_store[method_name] ||
         self.class.send(:__safe_memo_class_key_generators__)[method_name]
 
       if key_block
-        [method_name, key_block.call(*args, **kwargs)]
+        [effective_name, key_block.call(*args, **kwargs)]
       else
-        safe_memo_cache_key(method_name, args, kwargs)
+        bust_block = self.class.send(:__safe_memo_class_cache_bust_generators__)[method_name]
+        if bust_block
+          token = bust_block.is_a?(Symbol) ? send(bust_block) : instance_exec(&bust_block)
+          [effective_name, [deep_freeze_copy(args), deep_freeze_copy(kwargs), token]]
+        else
+          safe_memo_cache_key(effective_name, args, kwargs)
+        end
       end
     end
 

data/lib/safe_memoize/extension.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  # Mixin for defining SafeMemoize extensions.
+  #
+  # Extend this module in any Ruby module or class that you want to register
+  # as a SafeMemoize extension. It provides a DSL for declaring custom
+  # +memoize+ options and global cache lifecycle event handlers.
+  #
+  # @example Defining an extension
+  #   module MyExtension
+  #     extend SafeMemoize::Extension
+  #
+  #     handles_option :active_record_bust do |value, method_name, _options|
+  #       { cache_bust: -> { send(:updated_at) } }
+  #     end
+  #
+  #     on_cache_event :miss do |klass, method_name, _cache_key, _record|
+  #       Rails.logger.debug "cache miss: #{klass}##{method_name}"
+  #     end
+  #   end
+  #
+  #   SafeMemoize.register_extension(:active_record_bust, MyExtension)
+  module Extension
+    # Declares a custom +memoize+ option handled by this extension.
+    #
+    # The block is called at +memoize+ definition time whenever +option_name+
+    # appears in the +memoize+ keyword arguments. It receives the option value,
+    # the method name being memoized, and the full hash of other extension options
+    # passed to that +memoize+ call. It must return a +Hash+ of standard
+    # {ClassMethods#memoize} options to inject (e.g. +{ cache_bust: ... }+), or
+    # +nil+/empty hash for no injection.
+    #
+    # @param option_name [Symbol]
+    # @yieldparam value [Object] the option value supplied by the caller
+    # @yieldparam method_name [Symbol] the method being memoized
+    # @yieldparam all_options [Hash] other extension options in the same +memoize+ call
+    # @yieldreturn [Hash, nil] standard memoize options to inject
+    # @return [void]
+    def handles_option(option_name, &processor)
+      @__handled_options__ ||= {}
+      @__handled_options__[option_name.to_sym] = processor
+    end
+
+    # Registers a global cache lifecycle event handler.
+    #
+    # The block fires after every matching cache event across *all* memoized
+    # methods on all classes. Multiple event types can be listed in a single
+    # call. Valid types are +:on_hit+, +:on_miss+, +:on_store+, +:on_expire+,
+    # and +:on_evict+.
+    #
+    # Handlers execute on the main Ractor only; they are silently skipped from
+    # worker Ractors.
+    #
+    # @param event_types [Array<Symbol>] one or more of +:on_hit+, +:on_miss+,
+    #   +:on_store+, +:on_expire+, +:on_evict+
+    # @yieldparam klass [Class] the class whose instance triggered the event
+    # @yieldparam method_name [Symbol] bare method name (namespace stripped)
+    # @yieldparam cache_key [Array] the full cache key
+    # @yieldparam record [Hash, nil] the cache record (+value+, +expires_at+, +cached_at+)
+    # @return [void]
+    def on_cache_event(*event_types, &handler)
+      @__event_handlers__ ||= {}
+      event_types.each { |type| (@__event_handlers__[type.to_sym] ||= []) << handler }
+    end
+
+    # @api private
+    def handled_options
+      @__handled_options__&.keys || []
+    end
+
+    # @api private
+    def process_memoize_option(option_name, value, method_name, all_options)
+      processor = @__handled_options__&.[](option_name.to_sym)
+      result = processor&.call(value, method_name, all_options)
+      result.is_a?(Hash) ? result : {}
+    end
+
+    # @api private
+    def dispatch_cache_event(event_type, klass, method_name, cache_key, record)
+      return unless @__event_handlers__
+
+      (@__event_handlers__[event_type] || []).each do |handler|
+        handler.call(klass, method_name, cache_key, record)
+      end
+    end
+  end
+end