safe_memoize 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24faf0555ba5e11e37092aea14e1db090d7f5bb13dd40edc33ea30d8adcba552
-  data.tar.gz: '09beaa5cf9e25284462bdac9636929642213a9e8d657900d30913832da230959'
+  metadata.gz: e34f9a8aaa025eca2f817b633409686788e99442f10de2fede62f30443f9a0fc
+  data.tar.gz: 21560a08d7060ee77da109da4a91024899674da14ec41e051ff5cb08a5d913f2
 SHA512:
-  metadata.gz: 8ed21a58fc95a122794bcb91a1cbccae2bad598b38f736d76eb6f95551245dba070e047eaaea56b26fca6aace181e138acd37a0a027dbb7c0a6a43ae728f2cf0
-  data.tar.gz: f51afd15884dd10c771cd3f3ffcb7d481b0fd3012ecc74148fc9ff82e056abc1a2bb044d5344d635abb5380d200f0ec62a4db528d8fc79697358f775cc4aba3e
+  metadata.gz: '0408a2a2322c7861ec0eab88a62e02a15c59c552301e8fe3b7712691d03f385c81a2efbcf8ef06da57b50ae304edc18a7794001c43093b9fc49c180449a68199'
+  data.tar.gz: 421ad6f07416395bef2723fd00a20d7e20c4becd2fec0da9f774ca476d370b1bb459b8d895c2cb7535da9898e27afcfdfcf3d089923ff8aac426dee0c89c5aa8

data/.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: [eclectic-coding] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

data/CHANGELOG.md

@@ -8,6 +8,45 @@ from v1.0.0 onwards. Prior 0.x releases may include breaking changes between min
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-06-02
+
+### Added
+
+- `safe_memoize_options(**opts)` class-level macro — sets default options for every subsequent `memoize` call on the class. Per-call options take precedence; class defaults take precedence over global `SafeMemoize.configure` defaults. Accepts all `memoize` options except mode-switch options (`shared:`, `fiber_local:`, `ractor_safe:`, `shared_cache:`), which must be specified per call. Call with no arguments to clear class-level defaults.
+- `copy_on_read: true` option on `memoize` — returns a `dup` (or `deep_dup` when available, e.g. ActiveRecord objects) of the cached value on every read, preventing callers from mutating shared cached state. `nil` and frozen values are returned as-is. Works across all cache paths (per-instance, LRU, shared, fiber-local, and external store). Incompatible with `ractor_safe:` (ractor-safe values are always frozen; use that guarantee instead). Can be set as a class default via `safe_memoize_options copy_on_read: true`.
+
+## [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,12 @@ 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)
+- [Per-class default options via `safe_memoize_options` — set TTL, max size, copy-on-read, and other defaults for every `memoize` call on the class without repeating them](#per-class-default-options-safe_memoize_options)
+- [Copy-on-read via `copy_on_read: true` — returns a `dup`/`deep_dup` on every cache read to protect shared cached state from caller mutation](#copy-on-read)
 
 ## Installation
 
@@ -729,6 +735,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 +1028,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)
 
@@ -1092,6 +1374,83 @@ end
 
 [↑ Back to features](#features)
 
+## Per-class default options (`safe_memoize_options`)
+
+`safe_memoize_options` sets option defaults for every `memoize` call on the class, eliminating repetition when many methods share the same TTL, LRU cap, or other option. Per-call options still take precedence; class defaults take precedence over global `SafeMemoize.configure` defaults.
+
+```ruby
+class ApiClient
+  prepend SafeMemoize
+  safe_memoize_options ttl: 60, max_size: 200, copy_on_read: true
+
+  def fetch(id) = http.get(id)
+  memoize :fetch                     # uses ttl: 60, max_size: 200, copy_on_read: true
+
+  def list = http.get("/all")
+  memoize :list, ttl: 300            # uses max_size: 200, copy_on_read: true; ttl: 300 overrides
+end
+```
+
+Accepted options are the same as `memoize` minus the mode-switch options (`shared:`, `fiber_local:`, `ractor_safe:`, `shared_cache:`), which must be specified per call because they change the entire execution path:
+
+```ruby
+safe_memoize_options(
+  ttl:          60,
+  max_size:     100,
+  ttl_refresh:  true,
+  copy_on_read: true,
+  namespace:    "v2",
+  if:           ->(v) { v.present? },
+  cache_bust:   :updated_at
+)
+```
+
+Call with no arguments to clear all class-level defaults:
+
+```ruby
+MyClass.safe_memoize_options   # clears — subsequent memoize calls use global config or per-call options only
+```
+
+[↑ Back to features](#features)
+
+## Copy-on-read
+
+Pass `copy_on_read: true` to `memoize` to return a `dup` (or `deep_dup` when available, e.g. ActiveRecord objects) of the stored value on every cache read. This prevents callers from mutating the shared cached object:
+
+```ruby
+class ConfigService
+  prepend SafeMemoize
+
+  def settings = {host: "localhost", port: 8080}
+  memoize :settings, copy_on_read: true
+end
+
+svc = ConfigService.new
+result = svc.settings
+result[:host] = "mutated"   # only affects the caller's copy
+
+svc.settings[:host]         # => "localhost" — cache is unaffected
+```
+
+`nil` and frozen values are returned as-is (no dup attempted). `copy_on_read:` works across all cache paths: per-instance hash, LRU (`max_size:`), class-level shared (`shared: true`), fiber-local (`fiber_local: true`), and external stores. It is incompatible with `ractor_safe: true` (ractor-safe values are always frozen; rely on that guarantee instead).
+
+Set it as a class-wide default with `safe_memoize_options`:
+
+```ruby
+class ReportService
+  prepend SafeMemoize
+  safe_memoize_options copy_on_read: true
+
+  def summary = build_summary
+  memoize :summary
+
+  def details = build_details
+  memoize :details
+end
+```
+
+[↑ Back to features](#features)
+
 ## Ractor-safe shared cache
 
 Pass `ractor_safe: true` (together with `shared: true`) to replace the `Mutex`-backed class-level shared cache with a supervisor `Ractor` that owns the mutable cache hash. All reads and writes are serialised through message passing, so the cache is safe to use from multiple Ractors.
@@ -1222,6 +1581,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 +1607,11 @@ 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:` |
+| `copy_on_read:` | `Boolean` | `false` | Return a `dup`/`deep_dup` of the cached value on every read; protects shared state from caller mutation; nil and frozen values pass through; incompatible with `ractor_safe:` |
+| *(extension options)* | any | — | Unknown kwargs are validated against registered extensions; raise `ArgumentError` if unclaimed |
 
 ### `memoize_all` options (class method)
 
@@ -1249,6 +1624,12 @@ All `memoize` option keys above, plus:
 | `include_protected:` | `Boolean` | `false` |
 | `include_private:` | `Boolean` | `false` |
 
+### `safe_memoize_options` (class method)
+
+| Option key | Type | Default | Notes |
+|---|---|---|---|
+| any `memoize` key except mode-switches | — | — | Accepts `ttl:`, `max_size:`, `ttl_refresh:`, `if:`, `unless:`, `key:`, `cache_bust:`, `copy_on_read:`, `namespace:`, `store:`; raises `ArgumentError` for `shared:`, `fiber_local:`, `ractor_safe:`, `shared_cache:` |
+
 ### Instance methods (public)
 
 **Inspection**
@@ -1350,6 +1731,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

@@ -4,17 +4,44 @@ This document tracks the planned evolution of SafeMemoize through v1.0.0 and bey
 
 ---
 
+## v1.5.0 — Cache Invalidation
+
+*Goal: group-level cache invalidation so related methods can be busted in one operation.*
+
+| Feature | Description | Status |
+|---|---|---|
+| Memoization groups | `memoize :find, group: :database` then `reset_memo_group(:database)` to invalidate all methods tagged with the same group at once; groups can span multiple methods on the same class | Planned |
+
+---
+
+## v1.6.0 — Resilience
+
+*Goal: make external-store memoization resilient to infrastructure failures.*
+
+| Feature | Description | Status |
+|---|---|---|
+| Circuit breaker for external stores | When a `store:` adapter raises on `read` or `write`, automatically fall back to the per-instance in-process hash rather than propagating the exception; configurable error threshold and recovery probe interval | Planned |
+
+---
+
+## v1.7.0 — Advanced Store Features
+
+*Goal: multi-process performance patterns for high-traffic deployments.*
+
+| Feature | Description | Status |
+|---|---|---|
+| Multi-level (L1/L2) caching | `store: [memory_store, redis_store]` — check in-process first, fall back to the remote store on miss, and promote to L1 on read; each level can have independent TTL and eviction settings | Planned |
+| Stampede protection | Probabilistic early expiry (XFetch algorithm) for external stores; recomputes slightly before a TTL expires to prevent multiple processes hitting a cold miss simultaneously | Planned |
+
+---
+
 ## v2.0.0 — Next Generation (Long Horizon)
 
 *Goal: incorporate real-world usage feedback, clean up accumulated API surface, and open a path for advanced extension.*
 
 | 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