safe_memoize 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24faf0555ba5e11e37092aea14e1db090d7f5bb13dd40edc33ea30d8adcba552
-  data.tar.gz: '09beaa5cf9e25284462bdac9636929642213a9e8d657900d30913832da230959'
+  metadata.gz: 3e47bd422b1516a4f775e49ad3f58bf916df60c094aae7dfddf652fa78e44d73
+  data.tar.gz: 2adc318d5cda8858d1ee49a2dd32080acea1e8163807e424366d9e8e42a30943
 SHA512:
-  metadata.gz: 8ed21a58fc95a122794bcb91a1cbccae2bad598b38f736d76eb6f95551245dba070e047eaaea56b26fca6aace181e138acd37a0a027dbb7c0a6a43ae728f2cf0
-  data.tar.gz: f51afd15884dd10c771cd3f3ffcb7d481b0fd3012ecc74148fc9ff82e056abc1a2bb044d5344d635abb5380d200f0ec62a4db528d8fc79697358f775cc4aba3e
+  metadata.gz: de347fc9b0e6f9ad1385f0f5f3a1cc03595f9cf8b969f354cd87bd5173e318ec9af98cf31d2253617c369a8cd7ea9d6c08fbc489d22d30775b912f6867bab70f
+  data.tar.gz: '08153a2284f53e6110d4f3fae0a84ae72d2739bc0146e70cbabd5a6cce30b544122204623185ad96c1706c1de518feb583a227fd8b74018b896775f884ac7053'

data/CHANGELOG.md

@@ -8,6 +8,38 @@ from v1.0.0 onwards. Prior 0.x releases may include breaking changes between min
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-05-28
+
+### Added
+
+- `SafeMemoize::Extension` — mixin for building SafeMemoize extensions. Extend it in any module to get a DSL for declaring custom `memoize` options and global lifecycle event handlers without monkey-patching SafeMemoize internals.
+  - `handles_option(name, &processor)` — declares a custom keyword argument that `memoize` will accept; the processor block is called at definition time with `(value, method_name, all_extension_options)` and must return a `Hash` of standard memoize options to inject (e.g. `{cache_bust: ...}`, `{ttl: 60}`, `{namespace: "v2"}`).
+  - `on_cache_event(*event_types, &handler)` — registers a global lifecycle handler that fires after every matching event (`:on_hit`, `:on_miss`, `:on_store`, `:on_expire`, `:on_evict`) across all memoized methods on all classes; handler receives `(klass, method_name, cache_key, record)`; runs on the main Ractor only.
+  - Duck-type compatible — any object responding to `handled_options`, `process_memoize_option`, and `dispatch_cache_event` works without `extend SafeMemoize::Extension`.
+- `SafeMemoize.register_extension(name, extension)` — registers an extension under a symbolic name.
+- `SafeMemoize.unregister_extension(name)` — removes an extension.
+- `SafeMemoize.extensions` — returns a snapshot of the registry.
+- `SafeMemoize.reset_extensions!` — clears the registry (test teardown).
+- `SafeMemoize.extension_for_option(option_name)` — returns the registered extension that handles the named option, or `nil`.
+- `memoize` now accepts `**extension_options` for any unknown keyword argument; each key is validated against registered extensions at call time and raises `ArgumentError` if no extension claims it, preserving the existing strict-options behaviour for typos.
+
+- `cache_bust: callable` option on `memoize` — automatic cache invalidation driven by a version token. A callable (Proc, lambda, or Symbol naming an instance method) is invoked on the instance at every cache lookup; the returned token is folded into the cache key alongside the normal arguments. When the token changes (e.g. an ActiveRecord `updated_at` advances after a `save`), the old key no longer matches any entry — the method body is recomputed and stored under the new key without any explicit `reset_memo` call. Accepts a zero-argument callable invoked via `instance_exec` (giving access to `self`, instance variables, and methods) or a `Symbol` naming an instance method. Returns any comparable value as the token: a `Time`, `Integer`, `String`, `Array`, etc. Old token entries accumulate as stale; pair with `ttl:` or a store adapter's eviction to bound memory. Incompatible with `key:`. Composes with `namespace:`, `ttl:`, `if:`, `unless:`, and `shared_cache:`.
+
+- `shared_cache: "name"` option on `memoize` — routes all reads and writes through a globally-registered named `Stores::Base` instance, enabling cross-class cache sharing. Any number of unrelated classes can share the same backing store by referencing the same name. The store is resolved at `memoize` definition time via `SafeMemoize.shared_cache("name")`, which auto-creates a `Stores::Memory` instance on first access; supply a custom adapter (Redis, RailsCache, etc.) by calling `SafeMemoize.register_shared_cache("name", store)` before any class that references the name is loaded. Incompatible with `shared:`, `store:`, `fiber_local:`, `ractor_safe:`, and `max_size:`; composes naturally with `namespace:`, `ttl:`, `if:`, `unless:`, and `key:`.
+- `SafeMemoize.shared_cache(name)` — returns the `Stores::Base` instance for the given name, creating a new `Stores::Memory` if none is registered.
+- `SafeMemoize.register_shared_cache(name, store)` — registers a custom `Stores::Base` instance under a name; must be called before any class that uses that name via `shared_cache:` is loaded.
+- `SafeMemoize.clear_shared_cache(name)` — calls `clear` on the named store, evicting all entries. No-op for unregistered names.
+- `SafeMemoize.drop_shared_cache(name)` — removes the named store from the registry; subsequent `shared_cache(name)` calls will auto-create a new `Memory` store.
+- `SafeMemoize.shared_caches` — returns a dup of the current registry as a `Hash{String => Stores::Base}`.
+- `SafeMemoize.reset_shared_caches!` — clears the entire registry; useful in test-suite `after` hooks to prevent state leaking between examples.
+
+- `namespace:` option on `memoize` — a String prefix scoped to a single method; prepended to the cache key's first element so that entries with different namespaces never collide, even when sharing the same store or the same per-instance hash. Must be a non-empty string without `:`. Useful for versioning one method independently of its peers.
+- `.safe_memoize_namespace` / `.safe_memoize_namespace=` — class-level namespace attribute; applies to every `memoize` call on the class that does not specify its own `namespace:` option. Takes precedence over the global `SafeMemoize::Configuration#namespace`.
+- `SafeMemoize::Configuration#namespace` — global namespace prefix applied to every `memoize` call site that has no per-method or class-level namespace set. Set via `SafeMemoize.configure { |c| c.namespace = "v1" }`. Useful for versioned deployments and multi-tenant setups. Cleared by `reset_configuration!`.
+- Resolution priority: per-method `namespace:` > class `.safe_memoize_namespace` > global `Configuration#namespace`.
+- All introspection methods (`memoized?`, `memo_count`, `memo_keys`, `memo_values`, `reset_memo`, `reset_all_memos`, `dump_memo`, `cache_stats_for`, `cache_metrics_reset`, shared-cache equivalents, etc.) accept the bare method name regardless of which namespace tier is active; the `:method` field in projections always returns the bare method name.
+- Ractor-safe: namespace resolution uses `instance_variable_get` (read-only) so worker Ractors can call `compute_cache_key` without triggering unshareable class-level ivar initialization.
+
 ## [1.2.0] - 2026-05-27
 
 ### Added

data/README.md

@@ -73,6 +73,10 @@ SafeMemoize uses Ruby's `prepend` mechanism. When you call `memoize :method_name
 - [Class-level `.safe_memoize_store=` — set a per-class default store without touching global config](#class-level-default-store-safe_memoize_store)
 - [Fiber-local memoization via `fiber_local: true` — isolated per-fiber cache, no mutex, works with Async/Falcon](#fiber-local-memoization)
 - [Ractor-safe shared cache via `ractor_safe: true` — supervisor Ractor replaces the Mutex; worker Ractors can call the memoized method directly](#ractor-safe-shared-cache)
+- [Cache namespacing — per-method `namespace:`, class-level `.safe_memoize_namespace=`, and global `Configuration#namespace` for multi-tenant and versioned deployments](#cache-namespacing)
+- [Named shared caches via `shared_cache: "name"` — cross-class cache sharing backed by a globally-registered store](#named-shared-caches)
+- [Automatic cache busting via `cache_bust:` — version-token-based invalidation; works with ActiveRecord `updated_at` and any comparable value](#automatic-cache-busting)
+- [Plugin / extension architecture — `SafeMemoize::Extension` DSL for adding custom `memoize` options and global lifecycle handlers without monkey-patching](#plugin--extension-architecture)
 
 ## Installation
 
@@ -729,6 +733,282 @@ Metrics are per-instance and reset independently from the cache itself — clear
 
 [↑ Back to features](#features)
 
+### Plugin / extension architecture
+
+`SafeMemoize::Extension` lets third-party gems add custom `memoize` options and global lifecycle handlers without monkey-patching SafeMemoize internals.
+
+```ruby
+module MyExtension
+  extend SafeMemoize::Extension
+
+  # Declare a custom memoize option.
+  # The processor block runs at memoize definition time and returns
+  # a Hash of standard memoize options to inject.
+  handles_option :active_record_bust do |_value, _method_name, _options|
+    { cache_bust: -> { send(:updated_at) } }
+  end
+
+  # Register a global lifecycle handler (fires for every memoized method).
+  on_cache_event :miss do |klass, method_name, _cache_key, _record|
+    Rails.logger.debug "cache miss: #{klass}##{method_name}"
+  end
+end
+
+SafeMemoize.register_extension(:active_record_bust, MyExtension)
+```
+
+Once registered, the custom option is accepted by `memoize`:
+
+```ruby
+class OrderDecorator
+  prepend SafeMemoize
+
+  def initialize(order) = (@order = order)
+
+  def summary = expensive_compute(@order)
+  memoize :summary, active_record_bust: true
+  # ↑ MyExtension injects cache_bust: -> { updated_at } automatically
+end
+```
+
+#### `handles_option` processor return values
+
+The processor block must return a Hash of **standard** `memoize` option keys to inject. Any standard option is supported:
+
+```ruby
+handles_option :short_lived  do |ttl, _, _| { ttl: ttl }        end
+handles_option :versioned    do |ns,  _, _| { namespace: ns }    end
+handles_option :via_redis    do |store, _, _| { store: store }   end
+handles_option :bust_on      do |fn,  _, _| { cache_bust: fn }   end
+```
+
+#### `on_cache_event` handler signature
+
+```ruby
+on_cache_event :on_hit, :on_miss do |klass, method_name, cache_key, record|
+  # klass       — the class whose instance triggered the event
+  # method_name — bare Symbol (namespace stripped)
+  # cache_key   — full cache key Array
+  # record      — { value:, expires_at:, cached_at: } or nil
+end
+```
+
+Valid event types: `:on_hit`, `:on_miss`, `:on_store`, `:on_expire`, `:on_evict`.
+
+#### Registry API
+
+```ruby
+SafeMemoize.register_extension(:name, MyExtension)
+SafeMemoize.unregister_extension(:name)
+SafeMemoize.extensions               # { name: MyExtension, … }
+SafeMemoize.reset_extensions!        # clear registry (test teardown)
+SafeMemoize.extension_for_option(:active_record_bust)  # → MyExtension
+```
+
+#### Duck-type compatibility
+
+An extension does not need to `extend SafeMemoize::Extension`. Any object responding to `handled_options`, `process_memoize_option`, and `dispatch_cache_event` is accepted.
+
+#### Constraints
+
+- Unknown `memoize` keywords raise `ArgumentError` unless a registered extension claims them — typos are still caught.
+- `on_cache_event` handlers run on the main Ractor only; they are silently skipped from worker Ractors.
+
+[↑ Back to features](#features)
+
+### Automatic cache busting
+
+`cache_bust:` ties a method's cache lifetime to a version token derived from instance state. When the token changes, the old cache key no longer matches — the method is recomputed automatically, with no explicit `reset_memo` required.
+
+```ruby
+class OrderDecorator
+  prepend SafeMemoize
+
+  def initialize(order)
+    @order = order
+  end
+
+  def summary = expensive_compute(@order)
+  memoize :summary, cache_bust: -> { @order.updated_at }
+  # Saving @order advances updated_at → next call is a cache miss → fresh result
+end
+```
+
+#### Token forms
+
+```ruby
+# Proc/lambda — instance_exec gives full access to self, ivars, and methods
+memoize :report, cache_bust: -> { @record.updated_at }
+
+# Symbol — calls the named instance method
+memoize :data,   cache_bust: :cache_version
+
+# Compound token — any comparable value works, including arrays
+memoize :stats,  cache_bust: -> { [@version, tenant_id] }
+```
+
+#### How it works
+
+The token is incorporated into the cache key alongside the normal arguments. When the token changes, the old key simply produces no match — there is no deletion. Stale entries accumulate silently until:
+- They expire via `ttl:`, or
+- They are evicted by the store adapter's own eviction policy, or
+- You call `reset_memo(:method_name)` or `reset_all_memos` explicitly.
+
+For unbounded caches, pair with `ttl:` or a `max_size:`-capable store to limit memory growth:
+
+```ruby
+memoize :summary, cache_bust: -> { @order.updated_at }, ttl: 3600
+```
+
+#### Introspection
+
+All introspection methods work with the **current** token:
+
+```ruby
+obj.memoized?(:summary)       # true only if the current token's entry is live
+obj.memo_count(:summary)      # counts ALL live versions (current + stale)
+obj.reset_memo(:summary)      # clears ALL versions
+```
+
+#### Constraints
+
+- Incompatible with `key:` — both define the cache key shape; raises `ArgumentError` at `memoize` time.
+- Composes with `namespace:`, `ttl:`, `if:`, `unless:`, and `shared_cache:`.
+
+[↑ Back to features](#features)
+
+### Named shared caches
+
+`shared_cache: "name"` routes all cache reads and writes through a globally-registered store, letting unrelated classes share the same cached data without any object-level coordination.
+
+```ruby
+class OrderService
+  prepend SafeMemoize
+
+  def find(id) = Order.find(id)
+  memoize :find, shared_cache: "orders"
+end
+
+class OrderPresenter
+  prepend SafeMemoize
+
+  def find(id) = Order.find(id)          # same method signature
+  memoize :find, shared_cache: "orders"  # same backing store
+end
+
+# After OrderService.new.find(42) computes the value, OrderPresenter.new.find(42)
+# returns the cached result — the method body is not called a second time.
+```
+
+#### Registry API
+
+```ruby
+SafeMemoize.shared_cache("orders")                           # get or auto-create a Memory store
+SafeMemoize.register_shared_cache("orders", my_redis_store)  # use a custom adapter
+SafeMemoize.clear_shared_cache("orders")                     # evict all entries
+SafeMemoize.drop_shared_cache("orders")                      # remove from registry
+SafeMemoize.shared_caches                                    # { "orders" => #<Memory>, … }
+SafeMemoize.reset_shared_caches!                             # wipe registry (test teardown)
+```
+
+#### Custom adapter
+
+Register a Redis-backed (or any `Stores::Base`) store **before** any class that references the name is loaded — the store is captured at `memoize` definition time:
+
+```ruby
+# config/initializers/safe_memoize.rb
+require "safe_memoize/stores/redis"
+
+SafeMemoize.register_shared_cache(
+  "orders",
+  SafeMemoize::Stores::Redis.new(Redis.new, namespace: "myapp:orders")
+)
+```
+
+#### Key scoping and namespace composition
+
+By default two classes sharing the same cache name and method name share the same key:
+
+```ruby
+# OrderService#find(42) and OrderPresenter#find(42) → same key [:find, [42], {}]
+```
+
+Add `namespace:` when you want class-scoped entries within the same store:
+
+```ruby
+memoize :find, shared_cache: "orders", namespace: "service"    # [:"service:find", [42], {}]
+memoize :find, shared_cache: "orders", namespace: "presenter"  # [:"presenter:find", [42], {}]
+```
+
+#### Constraints
+
+- Incompatible with `shared:`, `store:`, `fiber_local:`, `ractor_safe:`, and `max_size:` (use the store adapter's own eviction policy).
+- `register_shared_cache` must be called before the class that uses the name is defined.
+- Test suites should call `SafeMemoize.reset_shared_caches!` in an `after` hook to prevent state leaking between examples.
+
+[↑ Back to features](#features)
+
+### Cache namespacing
+
+Namespacing adds a string prefix to every cache key, scoping entries to a logical partition. It is transparent to the rest of the API — introspection methods always accept and return bare method names regardless of the active namespace.
+
+Namespacing is particularly useful for:
+
+- **Versioned deployments** — change the namespace to instantly invalidate all in-flight cached values without flushing the whole store.
+- **Multi-tenant applications** — scope keys per tenant so different tenants' data cannot collide, even when sharing the same in-process hash or external store.
+
+#### Per-method namespace
+
+Pass `namespace:` to a single `memoize` call:
+
+```ruby
+class ApiClient
+  prepend SafeMemoize
+
+  def fetch(id) = http_get(id)
+  memoize :fetch, namespace: "v2"  # keys: [:"v2:fetch", [id], {}]
+end
+```
+
+#### Class-level namespace
+
+Set `.safe_memoize_namespace=` to apply a namespace to every `memoize` call on the class that doesn't specify its own:
+
+```ruby
+class OrderService
+  prepend SafeMemoize
+  self.safe_memoize_namespace = "orders"
+
+  def find(id) = Order.find(id)
+  memoize :find                       # keys: [:"orders:find", ...]
+
+  def stats = compute_stats
+  memoize :stats, namespace: "v2"     # per-method wins → [:"v2:stats", ...]
+end
+```
+
+#### Global namespace
+
+Set via `SafeMemoize.configure` to apply a namespace to every memoized method in the process that has no per-method or class-level namespace:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.namespace = "v1.2.3"   # bump this string on each deploy to bust all cached values
+end
+```
+
+#### Resolution priority
+
+`namespace:` option on `memoize` > `.safe_memoize_namespace` on the class > `SafeMemoize.configuration.namespace`
+
+#### Constraints
+
+- Namespace strings must be non-empty and must not contain `:`.
+- Namespacing works with all memoize paths (standard, `store:`, `fiber_local:`, `shared:`, `ractor_safe:`).
+- Adding or changing a namespace changes the cache keys, so existing entries become unreachable (they expire naturally or can be cleared by `reset_all_memos`).
+
+[↑ Back to features](#features)
+
 ### Global configuration
 
 Use `SafeMemoize.configure` to set defaults that apply to all subsequently memoized methods. Per-call options always take precedence over global defaults.
@@ -746,7 +1026,7 @@ Both settings apply at definition time — methods already memoized before `conf
 SafeMemoize.reset_configuration!
 ```
 
-The configure block also accepts `on_hook_error`, `on_deprecation`, `active_support_notifications`, `statsd_client`, and `default_store` (covered in [Hook error isolation](#hook-error-isolation), [Deprecation](#deprecation), [ActiveSupport::Notifications](#activesupportnotifications), [StatsD](#statsd), and [Pluggable cache stores](#pluggable-cache-stores)).
+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)
 
@@ -1222,6 +1502,17 @@ Anything **not** listed here — internal modules, private methods, `@__safe_mem
 | `SafeMemoize.configuration` | module method | Returns the current `Configuration` |
 | `SafeMemoize.reset_configuration!` | module method | Restores all configuration to defaults |
 | `SafeMemoize.deprecate(subject, message:, horizon:)` | module method | Emits a structured deprecation warning |
+| `SafeMemoize.shared_cache(name)` | module method | Returns named store, auto-creating a `Memory` store if absent |
+| `SafeMemoize.register_shared_cache(name, store)` | module method | Registers a custom `Stores::Base` under a name |
+| `SafeMemoize.clear_shared_cache(name)` | module method | Evicts all entries from the named store |
+| `SafeMemoize.drop_shared_cache(name)` | module method | Removes the named store from the registry |
+| `SafeMemoize.shared_caches` | module method | Returns a snapshot of the registry |
+| `SafeMemoize.reset_shared_caches!` | module method | Clears the entire registry (test teardown) |
+| `SafeMemoize.register_extension(name, ext)` | module method | Registers a plugin extension |
+| `SafeMemoize.unregister_extension(name)` | module method | Removes an extension |
+| `SafeMemoize.extensions` | module method | Returns snapshot of extension registry |
+| `SafeMemoize.reset_extensions!` | module method | Clears all extensions (test teardown) |
+| `SafeMemoize.extension_for_option(name)` | module method | Returns the extension handling the named option |
 
 ### `memoize` DSL (class method, added by `prepend SafeMemoize`)
 
@@ -1237,6 +1528,10 @@ Anything **not** listed here — internal modules, private methods, `@__safe_mem
 | `store:` | `Stores::Base \| nil` | `nil` | External cache store adapter; incompatible with `max_size:` and `shared:` |
 | `fiber_local:` | `Boolean` | `false` | Fiber-local cache; each fiber gets an isolated store; incompatible with `shared:` and `store:` |
 | `ractor_safe:` | `Boolean` | `false` | Supervisor-Ractor shared cache; replaces the `Mutex`; worker Ractors can call the method; requires `shared: true`; cached values are deep-frozen; incompatible with `if:`, `unless:`, `max_size:`, `ttl_refresh:`, `key:`, and `store:` |
+| `namespace:` | `String \| nil` | `nil` | Namespace prefix prepended to the cache key's first element; must not contain `:`; takes precedence over the class-level and global namespace |
+| `shared_cache:` | `String \| nil` | `nil` | Name of a globally-registered shared store; incompatible with `shared:`, `store:`, `fiber_local:`, `ractor_safe:`, and `max_size:` |
+| `cache_bust:` | `Proc \| Symbol \| nil` | `nil` | Version-token callable; invoked on the instance at each lookup; token is folded into the key; incompatible with `key:` |
+| *(extension options)* | any | — | Unknown kwargs are validated against registered extensions; raise `ArgumentError` if unclaimed |
 
 ### `memoize_all` options (class method)
 
@@ -1350,6 +1645,7 @@ All `memoize` option keys above, plus:
 | `statsd_client` | `Object \| nil` | `nil` |
 | `opentelemetry_tracer` | `Object \| nil` | `nil` |
 | `default_store` | `Stores::Base \| nil` | `nil` |
+| `namespace` | `String \| nil` | `nil` |
 
 ### Store adapter classes (v1.1.0+)
 

data/ROADMAP.md

@@ -10,11 +10,7 @@ This document tracks the planned evolution of SafeMemoize through v1.0.0 and bey
 
 | Feature | Description | Status |
 |---|---|---|
-| Plugin / extension architecture | A formal `SafeMemoize::Extension` API so third-party gems can add new options, hooks, or store adapters without monkey-patching | Planned |
 | DSL refinements | Evaluate alternative syntax proposals (`memoize_method`, block form, annotation approach) based on community feedback; introduce the preferred form with a migration path from the current API | Planned |
-| Cross-instance cache sharing | Beyond the class-level `shared: true`, support explicitly named shared caches that span unrelated classes | Planned |
-| Cache namespacing | Allow a namespace prefix on all keys for multi-tenant or versioned deployments (especially useful with external stores) | Planned |
-| Automatic cache busting | Optional integration with ActiveRecord's `updated_at` timestamp so object mutations automatically invalidate their own cached entries | Planned |
 
 ---
 

data/lib/safe_memoize/cache_metrics_methods.rb

@@ -9,15 +9,13 @@ module SafeMemoize
       @__safe_memo_metrics__ ||= {}
     end
 
-    def record_cache_hit(method_name, args, kwargs)
-      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+    def record_cache_hit(cache_key)
       metrics = memo_metrics_store
       metrics[cache_key] ||= {hits: 0, misses: 0, total_time: 0.0}
       metrics[cache_key][:hits] += 1
     end
 
-    def record_cache_miss(method_name, args, kwargs, computation_time)
-      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+    def record_cache_miss(cache_key, computation_time)
       metrics = memo_metrics_store
       metrics[cache_key] ||= {hits: 0, misses: 0, total_time: 0.0}
       metrics[cache_key][:misses] += 1
@@ -31,7 +29,8 @@ module SafeMemoize
     def _reset_cache_metrics_for(method_name)
       return unless defined?(@__safe_memo_metrics__) && @__safe_memo_metrics__
 
-      @__safe_memo_metrics__.delete_if { |key, _| key[0] == method_name }
+      effective = resolve_memo_key_name(method_name)
+      @__safe_memo_metrics__.delete_if { |key, _| key[0] == effective }
     end
   end
 end

data/lib/safe_memoize/class_methods.rb

@@ -38,6 +38,27 @@ module SafeMemoize
     #   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
     #
@@ -55,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, fiber_local: false, ractor_safe: false)
+    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
@@ -102,6 +142,13 @@ 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
@@ -122,6 +169,24 @@ module SafeMemoize
         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.
@@ -143,6 +208,7 @@ module SafeMemoize
       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
@@ -163,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
@@ -180,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
@@ -210,7 +276,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)
               memo_record_value(record)
             else
@@ -243,7 +309,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
@@ -288,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
@@ -319,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
@@ -349,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
@@ -365,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
@@ -374,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
@@ -387,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)
@@ -429,6 +495,31 @@ module SafeMemoize
       @__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:+.
@@ -470,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
@@ -500,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__
@@ -523,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
 
@@ -536,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__
@@ -563,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__
@@ -597,6 +697,25 @@ 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)
@@ -627,7 +746,7 @@ module SafeMemoize
             response = Ractor.receive_if { |m| m.is_a?(Array) && m[0] == tag }[1]
 
             if response[:hit]
-              record_cache_hit(method_name, args, kwargs)
+              record_cache_hit(cache_key)
               call_memo_hooks(:on_hit, cache_key, response[:record])
               return response[:record][:value]
             end
@@ -653,7 +772,7 @@ module SafeMemoize
             stored = Ractor.receive_if { |m| m.is_a?(Array) && m[0] == tag }[1]
             stored_record = stored[:stored]
 
-            record_cache_miss(method_name, args, kwargs, elapsed_time)
+            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)
 

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

data/lib/safe_memoize/fiber_local_methods.rb

@@ -42,7 +42,8 @@ module SafeMemoize
       return unless cache
 
       if args.empty? && kwargs.empty?
-        cache.delete_if { |key, _| key[0] == method_name }
+        effective = resolve_memo_key_name(method_name)
+        cache.delete_if { |key, _| key[0] == effective }
         fiber_memo_lru_or_nil&.delete(method_name)
       else
         cache_key = compute_cache_key(method_name, args, kwargs)

data/lib/safe_memoize/hooks_methods.rb

@@ -49,6 +49,8 @@ module SafeMemoize
       if (client = SafeMemoize.configuration.statsd_client)
         Adapters::StatsD.dispatch(client, hook_type, cache_key, self.class.name)
       end
+
+      SafeMemoize.dispatch_extension_events(hook_type, self.class, safe_memo_bare_method_name(cache_key[0]), cache_key, record)
     end
 
     def safe_memo_notify(hook_type, cache_key)

data/lib/safe_memoize/inspection_methods.rb

@@ -13,7 +13,8 @@ module SafeMemoize
 
     def memo_matcher_for(method_name, args, kwargs)
       if args.empty? && kwargs.empty?
-        ->(key) { key[0] == method_name }
+        effective = resolve_memo_key_name(method_name)
+        ->(key) { key[0] == effective }
       else
         cache_key = compute_cache_key(method_name, args, kwargs)
         ->(key) { key == cache_key }
@@ -28,7 +29,8 @@ module SafeMemoize
       entries = cache.to_a
       return entries unless method_name
 
-      entries.select { |(cache_key, _)| cache_key[0] == method_name }
+      effective = resolve_memo_key_name(method_name)
+      entries.select { |(cache_key, _)| cache_key[0] == effective }
     end
 
     def safe_memo_count_for(method_name)
@@ -57,14 +59,14 @@ module SafeMemoize
       # Custom keys are [method, custom_key] (2 elements); default keys are
       # [method, args, kwargs] (3 elements). Detect and surface accordingly.
       if cache_key.length == 2
-        method_name, custom_key = cache_key
+        effective_name, custom_key = cache_key
         payload = {custom_key: custom_key}
       else
-        method_name, args, kwargs = cache_key
+        effective_name, args, kwargs = cache_key
         payload = {args: args, kwargs: kwargs}
       end
 
-      payload[:method] = method_name if include_method
+      payload[:method] = safe_memo_bare_method_name(effective_name) if include_method
       payload[:value] = memo_record_value(value) if include_value
       payload
     end
@@ -73,6 +75,33 @@ module SafeMemoize
       [method_name.to_sym, deep_freeze_copy(args), deep_freeze_copy(kwargs)]
     end
 
+    # Returns the active namespace string for a bare method name, or nil.
+    # Priority: per-method namespace: option > class safe_memoize_namespace > global.
+    #
+    # Uses instance_variable_get throughout so this is safe to call from worker
+    # Ractors (reads only; lazy-init ivars must not be triggered in that context).
+    def __safe_memo_resolve_namespace__(method_name)
+      ns_map = self.class.instance_variable_get(:@__safe_memo_method_namespaces__)
+      (ns_map && ns_map[method_name]) ||
+        self.class.instance_variable_get(:@__safe_memoize_namespace__) ||
+        SafeMemoize.instance_variable_get(:@configuration)&.namespace
+    end
+
+    # Returns the effective cache key sym for a bare method name, applying any
+    # active namespace (per-method > class-level > global).
+    def resolve_memo_key_name(method_name)
+      ns = __safe_memo_resolve_namespace__(method_name)
+      ns ? :"#{ns}:#{method_name}" : method_name
+    end
+
+    # Strips the namespace prefix from an effective key sym, returning the bare
+    # method name. When no namespace is present the sym is returned unchanged.
+    def safe_memo_bare_method_name(key_sym)
+      s = key_sym.to_s
+      colon_idx = s.index(":")
+      colon_idx ? s[(colon_idx + 1)..].to_sym : key_sym
+    end
+
     def deep_freeze_copy(obj)
       case obj
       when Array

data/lib/safe_memoize/public_methods.rb

@@ -214,7 +214,8 @@ module SafeMemoize
 
       with_memo_lock do
         cache = memo_cache_or_nil || {}
-        entries = method_name ? cache.select { |key, _| key[0] == method_name } : cache.dup
+        effective = method_name && resolve_memo_key_name(method_name)
+        entries = effective ? cache.select { |key, _| key[0] == effective } : cache.dup
         entries.select! { |_, record| memo_record_live?(record) }
         entries.transform_values { |record| memo_record_value(record) }
       end
@@ -401,7 +402,7 @@ module SafeMemoize
 
         age = (now - record[:cached_at]).round(6) if record[:cached_at]
 
-        metrics_key = safe_memo_cache_key(method_name, args, kwargs)
+        metrics_key = compute_cache_key(method_name, args, kwargs)
         entry_metrics = memo_metrics_store[metrics_key] || {hits: 0, misses: 0}
 
         custom_key = (cache_key.length == 2) ? cache_key[1] : nil

data/lib/safe_memoize/public_metrics_methods.rb

@@ -26,7 +26,8 @@ module SafeMemoize
       method_name = method_name.to_sym
 
       with_memo_lock do
-        metrics = memo_metrics_store.select { |key, _| key[0] == method_name }
+        effective = resolve_memo_key_name(method_name)
+        metrics = memo_metrics_store.select { |key, _| key[0] == effective }
         return empty_stats.merge(method: method_name) if metrics.empty?
 
         aggregate_metrics(metrics, include_method: false).merge(method: method_name)
@@ -73,13 +74,13 @@ module SafeMemoize
       avg_time = total_misses.zero? ? 0.0 : (total_time / total_misses).round(6)
 
       entries = metrics.map do |cache_key, stats|
-        method_name, args, _kwargs = cache_key
+        effective_name, args, _kwargs = cache_key
         entry_calls = stats[:hits] + stats[:misses]
         entry_hit_rate = entry_calls.zero? ? 0.0 : (stats[:hits].to_f / entry_calls * 100).round(2)
 
         entry = {args: args, hits: stats[:hits], misses: stats[:misses],
                  hit_rate: entry_hit_rate, computation_time: stats[:total_time].round(6)}
-        entry[:method] = method_name if include_method
+        entry[:method] = safe_memo_bare_method_name(effective_name) if include_method
         entry
       end
 

data/lib/safe_memoize/version.rb

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

data/lib/safe_memoize.rb

@@ -2,6 +2,7 @@
 
 require_relative "safe_memoize/version"
 require_relative "safe_memoize/configuration"
+require_relative "safe_memoize/extension"
 require_relative "safe_memoize/stores/base"
 require_relative "safe_memoize/stores/memory"
 require_relative "safe_memoize/adapters/statsd"
@@ -54,6 +55,16 @@ module SafeMemoize
   # Rescue this to catch any error raised by the library itself.
   class Error < StandardError; end
 
+  # @api private
+  SHARED_CACHE_REGISTRY = {}
+  # @api private
+  SHARED_CACHE_MUTEX = Mutex.new
+
+  # @api private
+  EXTENSION_REGISTRY = {}
+  # @api private
+  EXTENSION_MUTEX = Mutex.new
+
   include InstanceMethods
 
   # @api private
@@ -102,4 +113,131 @@ module SafeMemoize
     handler = configuration.on_deprecation
     handler ? handler.call(text) : warn(text)
   end
+
+  # Returns the named shared cache store, creating a new in-process
+  # {Stores::Memory} instance if one has not been registered under +name+.
+  #
+  # Use {register_shared_cache} to supply a custom adapter (e.g. Redis) before
+  # any class that references the same name is loaded.
+  #
+  # @param name [String] the logical cache name
+  # @return [Stores::Base]
+  def self.shared_cache(name)
+    SHARED_CACHE_MUTEX.synchronize do
+      SHARED_CACHE_REGISTRY[name] ||= Stores::Memory.new
+    end
+  end
+
+  # Registers a custom store under +name+, replacing any existing entry.
+  #
+  # Must be called *before* any class that references +name+ via +shared_cache:+
+  # is loaded, because the store is captured at +memoize+ definition time.
+  #
+  # @param name [String] the logical cache name
+  # @param store [Stores::Base] any {Stores::Base} subclass instance
+  # @return [Stores::Base] the registered store
+  # @raise [ArgumentError] if +store+ is not a {Stores::Base} instance
+  def self.register_shared_cache(name, store)
+    unless store.is_a?(Stores::Base)
+      raise ArgumentError, "store must be a SafeMemoize::Stores::Base instance (got #{store.class})"
+    end
+    SHARED_CACHE_MUTEX.synchronize { SHARED_CACHE_REGISTRY[name] = store }
+  end
+
+  # Clears all entries in the named shared cache without removing it from the
+  # registry. A no-op when no cache is registered under +name+.
+  #
+  # @param name [String]
+  # @return [void]
+  def self.clear_shared_cache(name)
+    SHARED_CACHE_MUTEX.synchronize { SHARED_CACHE_REGISTRY[name]&.clear }
+  end
+
+  # Removes the named shared cache from the registry entirely.
+  # Subsequent +shared_cache(name)+ calls will create a fresh store.
+  #
+  # @param name [String]
+  # @return [Stores::Base, nil] the removed store, or +nil+ if not present
+  def self.drop_shared_cache(name)
+    SHARED_CACHE_MUTEX.synchronize { SHARED_CACHE_REGISTRY.delete(name) }
+  end
+
+  # Returns a snapshot of the current registry as a plain +Hash+.
+  #
+  # @return [Hash{String => Stores::Base}]
+  def self.shared_caches
+    SHARED_CACHE_MUTEX.synchronize { SHARED_CACHE_REGISTRY.dup }
+  end
+
+  # Removes all named shared caches from the registry.
+  #
+  # Useful in test suite +after+ hooks to prevent state leaking between examples.
+  #
+  # @return [void]
+  def self.reset_shared_caches!
+    SHARED_CACHE_MUTEX.synchronize { SHARED_CACHE_REGISTRY.clear }
+  end
+
+  # Registers an extension under +name+.
+  #
+  # An extension is any Ruby object that optionally responds to the
+  # {Extension} interface: {Extension#handled_options}, {Extension#process_memoize_option},
+  # and {Extension#dispatch_cache_event}. Use {Extension} as a mixin to get a
+  # convenient DSL for defining these.
+  #
+  # @param name [Symbol, String] a unique identifier for this extension
+  # @param extension [Object] the extension object or module
+  # @return [Object] the registered extension
+  def self.register_extension(name, extension)
+    EXTENSION_MUTEX.synchronize { EXTENSION_REGISTRY[name.to_sym] = extension }
+  end
+
+  # Removes an extension from the registry.
+  #
+  # @param name [Symbol, String]
+  # @return [Object, nil] the removed extension, or +nil+ if not present
+  def self.unregister_extension(name)
+    EXTENSION_MUTEX.synchronize { EXTENSION_REGISTRY.delete(name.to_sym) }
+  end
+
+  # Returns a snapshot of all registered extensions as a +Hash+.
+  #
+  # @return [Hash{Symbol => Object}]
+  def self.extensions
+    EXTENSION_MUTEX.synchronize { EXTENSION_REGISTRY.dup }
+  end
+
+  # Removes all registered extensions.
+  #
+  # Useful in test suite +after+ hooks to prevent state leaking between examples.
+  #
+  # @return [void]
+  def self.reset_extensions!
+    EXTENSION_MUTEX.synchronize { EXTENSION_REGISTRY.clear }
+  end
+
+  # Returns the first registered extension that declares it handles +option_name+,
+  # or +nil+ if none does.
+  #
+  # @param option_name [Symbol]
+  # @return [Object, nil]
+  def self.extension_for_option(option_name)
+    sym = option_name.to_sym
+    EXTENSION_MUTEX.synchronize do
+      EXTENSION_REGISTRY.values.find do |ext|
+        ext.respond_to?(:handled_options) && ext.handled_options.include?(sym)
+      end
+    end
+  end
+
+  # Dispatches a cache lifecycle event to all registered extensions that
+  # respond to +dispatch_cache_event+.
+  #
+  # @api private
+  def self.dispatch_extension_events(event_type, klass, method_name, cache_key, record)
+    exts = EXTENSION_MUTEX.synchronize { EXTENSION_REGISTRY.values.dup }
+    exts.each do |ext|
+      ext.dispatch_cache_event(event_type, klass, method_name, cache_key, record) if ext.respond_to?(:dispatch_cache_event)
+    end
+  end
 end

data/sig/safe_memoize.rbs

@@ -18,11 +18,36 @@ module SafeMemoize
   @__safe_memo_shared_mutex__: Mutex?
   @__safe_memo_shared_lru_order__: Hash[Symbol, Hash[memo_key, true]]?
 
+  SHARED_CACHE_REGISTRY: Hash[String, Stores::Base]
+  SHARED_CACHE_MUTEX: Mutex
+  EXTENSION_REGISTRY: Hash[Symbol, untyped]
+  EXTENSION_MUTEX: Mutex
+
   def self.prepended: (Class base) -> void
   def self.configure: () { (Configuration) -> void } -> void
   def self.configuration: () -> Configuration
   def self.reset_configuration!: () -> Configuration
   def self.deprecate: (String subject, message: String, horizon: String) -> void
+  def self.shared_cache: (String name) -> Stores::Base
+  def self.register_shared_cache: (String name, Stores::Base store) -> Stores::Base
+  def self.clear_shared_cache: (String name) -> void
+  def self.drop_shared_cache: (String name) -> Stores::Base?
+  def self.shared_caches: () -> Hash[String, Stores::Base]
+  def self.reset_shared_caches!: () -> void
+  def self.register_extension: (Symbol | String name, untyped extension) -> untyped
+  def self.unregister_extension: (Symbol | String name) -> untyped?
+  def self.extensions: () -> Hash[Symbol, untyped]
+  def self.reset_extensions!: () -> void
+  def self.extension_for_option: (Symbol option_name) -> untyped?
+  def self.dispatch_extension_events: (Symbol event_type, Class klass, Symbol method_name, untyped cache_key, untyped record) -> void
+
+  module Extension
+    def handles_option: (Symbol option_name) { (untyped value, Symbol method_name, Hash[Symbol, untyped] all_options) -> Hash[Symbol, untyped]? } -> void
+    def on_cache_event: (*Symbol event_types) { (Class klass, Symbol method_name, untyped cache_key, untyped record) -> void } -> void
+    def handled_options: () -> Array[Symbol]
+    def process_memoize_option: (Symbol option_name, untyped value, Symbol method_name, Hash[Symbol, untyped] all_options) -> Hash[Symbol, untyped]
+    def dispatch_cache_event: (Symbol event_type, Class klass, Symbol method_name, untyped cache_key, untyped record) -> void
+  end
 
   class Configuration
     attr_accessor default_ttl: Numeric?
@@ -33,15 +58,18 @@ module SafeMemoize
     attr_accessor statsd_client: untyped
     attr_accessor opentelemetry_tracer: untyped
     attr_accessor default_store: Stores::Base?
+    attr_accessor namespace: String?
 
     def initialize: () -> void
   end
 
   module ClassMethods
-    def memoize: (Symbol | String method_name, ?ttl: Numeric?, ?max_size: Integer?, ?ttl_refresh: bool, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?store: Stores::Base?, ?fiber_local: bool, ?ractor_safe: bool) -> void
+    def memoize: (Symbol | String method_name, ?ttl: Numeric?, ?max_size: Integer?, ?ttl_refresh: bool, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?store: Stores::Base?, ?fiber_local: bool, ?ractor_safe: bool, ?namespace: String?, ?shared_cache: String?, ?cache_bust: (^() -> untyped) | Symbol | nil, **untyped extension_options) -> void
     def safe_memoize_store: () -> Stores::Base?
     def safe_memoize_store=: (Stores::Base?) -> Stores::Base?
-    def memoize_all: (?except: Array[Symbol | String], ?only: Array[Symbol | String], ?include_protected: bool, ?include_private: bool, ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?fiber_local: bool) -> void
+    def safe_memoize_namespace: () -> String?
+    def safe_memoize_namespace=: (String?) -> String?
+    def memoize_all: (?except: Array[Symbol | String], ?only: Array[Symbol | String], ?include_protected: bool, ?include_private: bool, ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?fiber_local: bool, ?namespace: String?, ?shared_cache: String?) -> void
     def reset_shared_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
     def reset_all_shared_memos: () -> void
     def shared_memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) -> bool
@@ -55,6 +83,8 @@ module SafeMemoize
     def __safe_memo_shared_mutex__: () -> Mutex
     def __safe_memo_shared_lru_order__: () -> Hash[Symbol, Hash[memo_key, true]]
     def __safe_memo_class_key_generators__: () -> Hash[Symbol, Proc]
+    def __safe_memo_method_namespaces__: () -> Hash[Symbol, String]
+    def __safe_memo_class_cache_bust_generators__: () -> Hash[Symbol, Proc | Symbol]
     def memoized_method_visibility: (Symbol method_name) -> Symbol
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -61,6 +61,7 @@ files:
 - lib/safe_memoize/class_methods.rb
 - lib/safe_memoize/configuration.rb
 - lib/safe_memoize/custom_key_methods.rb
+- lib/safe_memoize/extension.rb
 - lib/safe_memoize/fiber_local_methods.rb
 - lib/safe_memoize/hooks_methods.rb
 - lib/safe_memoize/inspection_methods.rb