safe_memoize 0.8.0 → 1.0.0

data/README.md

@@ -14,7 +14,7 @@ Beyond the basics, SafeMemoize ships with TTL expiration (including sliding wind
 
 ## The Problem
 
-Ruby's common memoization pattern breaks with falsy values:
+Ruby's common memoization pattern breaks with falsy values: 
 
 ```ruby
 def user
@@ -51,6 +51,22 @@ SafeMemoize uses Ruby's `prepend` mechanism. When you call `memoize :method_name
 - [Bulk memoization via `memoize_all` (public, protected, and private)](#bulk-memoization)
 - [Custom cache key generation per method](#custom-cache-keys)
 - [TTL introspection via `memo_ttl_remaining`](#cache-inspection)
+- [Deep single-entry inspection via `memo_inspect`](#cache-inspection)
+- [`ArgumentError` at definition time when memoizing an undefined method](#basic-memoization)
+- [Hook error isolation — hook exceptions never propagate to callers](#lifecycle-hooks)
+- [Deprecation infrastructure for gem authors](#deprecation)
+- [Optional `ActiveSupport::Notifications` integration for Rails observability](#activesupportnotifications)
+- [Optional StatsD adapter for metrics pipelines](#statsd)
+- [Optional OpenTelemetry adapter for distributed tracing](#opentelemetry)
+- [Rails request-scope helpers for controllers and service objects](#rails-request-scope)
+- [Batch cache warm-up via `memo_preload`](#cache-warm-up-and-persistence)
+- [`on_memo_store` hook fires on every cache write](#lifecycle-hooks)
+- [Global default TTL and max size via `SafeMemoize.configure`](#global-configuration)
+- [`memo_touch` resets the expiry clock without recomputing](#ttl-expiration)
+- [`memo_refresh` force-recomputes and re-caches in one call](#cache-inspection)
+- [`memo_age` and `memo_stale?` for TTL introspection](#cache-inspection)
+- [Class-level `key:` option for shared cache key generation](#custom-cache-keys)
+- [`shared_memo_age` and `shared_memo_stale?` for shared cache TTL inspection](#shared-cache)
 
 ## Installation
 
@@ -88,6 +104,10 @@ class UserService
 end
 ```
 
+Calling `memoize` on a method name that does not exist raises `ArgumentError` immediately at class definition time rather than at the first runtime call.
+
+[↑ Back to features](#features)
+
 ### With arguments
 
 Results are cached per unique argument combination:
@@ -109,6 +129,10 @@ calc.compute(1, 2)  # returns cached result
 calc.compute(3, 4)  # computes and caches (different args)
 ```
 
+Argument arrays, hashes, and strings are deep-frozen into an independent copy when the cache key is built, so mutating arguments after a call cannot corrupt or miss a cached entry.
+
+[↑ Back to features](#features)
+
 ### Nil and false safety
 
 ```ruby
@@ -123,6 +147,8 @@ class Config
 end
 ```
 
+[↑ Back to features](#features)
+
 ### Works with private methods
 
 ```ruby
@@ -142,6 +168,8 @@ class TokenProvider
 end
 ```
 
+[↑ Back to features](#features)
+
 ### Cache reset
 
 ```ruby
@@ -152,6 +180,8 @@ obj.reset_memo(:search, "ruby", page: 2)       # Clears one positional/keyword c
 obj.reset_all_memos                             # Clears all memoized values
 ```
 
+[↑ Back to features](#features)
+
 ### Lifecycle hooks
 
 Register callbacks that fire when cached entries are evicted or expire.
@@ -188,6 +218,14 @@ obj.on_memo_expire do |cache_key, record|
 end
 ```
 
+**`on_memo_store`** fires whenever a value is written to the cache — on a miss, via `warm_memo`, or via `load_memo`:
+
+```ruby
+obj.on_memo_store do |cache_key, record|
+  Rails.logger.debug("Stored #{cache_key[0]}: #{record[:value].inspect}")
+end
+```
+
 Multiple hooks of the same type can be registered and all will fire. Remove them with `clear_memo_hooks`:
 
 ```ruby
@@ -200,6 +238,28 @@ obj.clear_memo_hooks              # Clears all hooks
 
 Hooks are per-instance and do not affect other objects of the same class.
 
+#### Hook error isolation
+
+Exceptions raised inside a hook never propagate to the caller. By default a warning is emitted to stderr:
+
+```
+[SafeMemoize] Hook error in on_miss: undefined method `log' for nil
+```
+
+Configure a custom handler via `SafeMemoize.configure`:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.on_hook_error = ->(error, hook_type, cache_key) {
+    MyErrorTracker.capture(error, context: { hook: hook_type, key: cache_key })
+  }
+end
+```
+
+Set `c.on_hook_error = :raise` to re-raise exceptions instead of swallowing them.
+
+[↑ Back to features](#features)
+
 ### TTL expiration
 
 ```ruby
@@ -215,6 +275,23 @@ end
 
 With a TTL, cached values expire automatically after the given number of seconds. The next call recomputes and refreshes the cache.
 
+Use `memo_touch` to reset the expiry clock on a cached entry without recomputing its value:
+
+```ruby
+obj.memo_touch(:current_quote)               # Resets TTL to the original duration
+obj.memo_touch(:current_quote, ttl: 120)     # Resets TTL to a new duration
+# => true on success, false if the entry is not cached or already expired
+```
+
+Use `memo_refresh` to force-recompute a cached entry immediately and store the new value:
+
+```ruby
+obj.memo_refresh(:current_quote)             # Recomputes and re-caches
+obj.memo_refresh(:find, 42)                  # Recomputes for one argument combination
+```
+
+[↑ Back to features](#features)
+
 ### Sliding window TTL
 
 Add `ttl_refresh: true` to reset the expiry clock on every cache hit, so the entry only expires after a full TTL of inactivity:
@@ -232,6 +309,8 @@ end
 
 Without `ttl_refresh:`, the entry expires 300 seconds after it was first cached. With it, the clock resets on every read — the entry is evicted only if the method goes 300 seconds without being called. `ttl_refresh: true` requires `ttl:` to be set and works with both per-instance and `shared: true` memoization.
 
+[↑ Back to features](#features)
+
 ### LRU cache size limit
 
 Pass `max_size:` to cap how many entries a method can hold. When the limit is reached the least-recently-used entry is evicted to make room:
@@ -265,6 +344,8 @@ memoize :find, max_size: 50, ttl: 300
 
 The `on_evict` hook fires for LRU-evicted entries the same way it does for manual `reset_memo` calls.
 
+[↑ Back to features](#features)
+
 ### Conditional caching
 
 Use `if:` to cache a result only when the predicate returns truthy, or `unless:` to skip caching when it returns truthy. Calls that don't satisfy the condition recompute every time until they do.
@@ -299,8 +380,25 @@ Both options accept any callable and compose with `ttl:` and `max_size:`:
 memoize :find, if: ->(result) { !result.nil? }, ttl: 60, max_size: 500
 ```
 
+[↑ Back to features](#features)
+
 ### Cache warm-up and persistence
 
+#### Batch warm-up via `memo_preload`
+
+Use `memo_preload` to warm multiple argument combinations in one call. It calls the memoized method for each argument set, caches all results, and returns them in input order:
+
+```ruby
+obj.memo_preload(:find, [1], [2], [3])
+# => [<User id=1>, <User id=2>, <User id=3>]
+```
+
+Each element is a separate argument list passed to the method, so keyword arguments work too:
+
+```ruby
+obj.memo_preload(:search, ["ruby"], ["rails"], ["rspec"])
+```
+
 #### Warming individual entries
 
 Use `warm_memo` to pre-populate a cache entry without calling the method. The block provides the value:
@@ -348,6 +446,8 @@ obj.load_memo(Marshal.load(raw)) if raw
 
 Loaded entries have no TTL — they persist until explicitly reset. Expired entries are excluded from `dump_memo` output, so snapshots never contain stale data.
 
+[↑ Back to features](#features)
+
 ### Shared cache
 
 Pass `shared: true` to store results on the class instead of per-instance. All instances share one cache, so the method is computed only once regardless of how many objects exist.
@@ -382,6 +482,8 @@ ConfigService.shared_memoized?(:database_url)         # => true
 ConfigService.shared_memoized?(:find, user_id)        # Checks one argument combination
 ConfigService.shared_memo_count                       # Total shared cached entries
 ConfigService.shared_memo_count(:find)                # Entries for one method
+ConfigService.shared_memo_age(:feature_flags)         # => 42.1  (seconds since cached)
+ConfigService.shared_memo_stale?(:feature_flags)      # => false (TTL not yet elapsed)
 ```
 
 `shared: true` supports `ttl:`, `ttl_refresh:`, `if:`, `unless:`, and `max_size:` options.
@@ -394,6 +496,8 @@ memoize :find, shared: true, max_size: 500
 
 Hooks (`on_memo_hit`, `on_memo_miss`, `on_memo_expire`, `on_memo_evict`) fire on the calling instance as usual.
 
+[↑ Back to features](#features)
+
 ### Bulk memoization
 
 Use `memoize_all` to memoize every public method defined on the class in one call:
@@ -432,6 +536,14 @@ Use `except:` to skip specific methods:
 memoize_all except: [:version, :name]
 ```
 
+Use `only:` to explicitly list the methods to memoize and skip all others:
+
+```ruby
+memoize_all only: [:database_url, :redis_url]
+```
+
+`only:` and `except:` are mutually exclusive — passing both raises `ArgumentError`.
+
 By default only public methods defined directly on the class are memoized. Use `include_protected:` or `include_private:` to opt those visibilities in:
 
 ```ruby
@@ -442,9 +554,11 @@ memoize_all include_protected: true, include_private: true
 
 Inherited methods are never affected regardless of visibility.
 
+[↑ Back to features](#features)
+
 ### Custom cache keys
 
-By default the cache key is derived from the method name and all arguments. Use `memoize_with_custom_key` on an instance to control exactly what makes two calls equivalent:
+By default the cache key is derived from the method name and all arguments. Use the `key:` option on `memoize` to set a class-level key generator that applies to every instance:
 
 ```ruby
 class ReportService
@@ -453,9 +567,18 @@ class ReportService
   def generate(user_id, options)
     build_report(user_id, options)
   end
-  memoize :generate
+  memoize :generate, key: ->(user_id, _options) { user_id }
 end
 
+# All instances share the same key logic — calls with the same user_id share one cache entry
+svc = ReportService.new
+svc.generate(42, {format: :pdf})  # computes and caches under key 42
+svc.generate(42, {format: :csv})  # cache hit — same key
+```
+
+For per-instance key overrides, use `memoize_with_custom_key` on an instance (takes priority over the class-level `key:` option):
+
+```ruby
 svc = ReportService.new
 
 # Cache only by user_id — ignore the options hash entirely
@@ -480,6 +603,8 @@ svc.clear_custom_keys(:generate)  # Remove generator for one method
 svc.clear_custom_keys             # Remove all custom key generators
 ```
 
+[↑ Back to features](#features)
+
 ### Cache inspection
 
 ```ruby
@@ -500,8 +625,32 @@ obj.memo_values(:search)                  # Cached signatures and values for one
 obj.memo_ttl_remaining(:current_quote)           # => 47.231 (seconds until expiry)
 obj.memo_ttl_remaining(:current_user)            # => nil    (no TTL set)
 obj.memo_ttl_remaining(:find, 42)                # => 0      (not cached or already expired)
+
+obj.memo_age(:current_quote)                     # => 12.8   (seconds since cached; nil if not cached)
+obj.memo_stale?(:current_quote)                  # => false  (cached but TTL not yet elapsed)
+obj.memo_stale?(:current_user)                   # => false  (no TTL — never stale)
 ```
 
+`memo_inspect` returns all metadata for one cached entry in a single mutex-held read:
+
+```ruby
+obj.memo_inspect(:find, 42)
+# => {
+#      cached: true,
+#      value: <result>,
+#      hits: 5,
+#      misses: 1,
+#      ttl_remaining: 47.2,
+#      age: 12.8,
+#      custom_key: nil,
+#      lru_position: 1
+#    }
+```
+
+Returns `nil` when the entry is not cached.
+
+[↑ Back to features](#features)
+
 ### Cache metrics
 
 Each instance tracks hits, misses, and computation time automatically.
@@ -521,18 +670,251 @@ obj.cache_stats
 #      ]
 #    }
 
-obj.cache_stats_for(:find)   # Stats scoped to one method
-obj.cache_hit_rate           # => 84.0  (percentage)
-obj.cache_miss_rate          # => 16.0  (percentage)
-obj.cache_metrics_reset      # Clears all collected metrics
+obj.cache_stats_for(:find)        # Stats scoped to one method
+obj.cache_hit_rate                # => 84.0  (percentage)
+obj.cache_miss_rate               # => 16.0  (percentage)
+obj.cache_metrics_reset           # Clears all collected metrics
+obj.cache_metrics_reset(:find)    # Clears metrics for one method only
 ```
 
 Metrics are per-instance and reset independently from the cache itself — clearing metrics does not evict cached values.
 
+[↑ Back to features](#features)
+
+### Global configuration
+
+Use `SafeMemoize.configure` to set defaults that apply to all subsequently memoized methods. Per-call options always take precedence over global defaults.
+
+```ruby
+SafeMemoize.configure do |c|
+  c.default_ttl      = 300   # All memoized methods expire after 5 minutes unless overridden
+  c.default_max_size = 100   # All memoized methods cap at 100 entries unless overridden
+end
+```
+
+Both settings apply at definition time — methods already memoized before `configure` is called are not affected. Reset all defaults back to `nil` with:
+
+```ruby
+SafeMemoize.reset_configuration!
+```
+
+The configure block also accepts `on_hook_error`, `on_deprecation`, `active_support_notifications`, and `statsd_client` (covered in [Hook error isolation](#hook-error-isolation), [Deprecation](#deprecation), [ActiveSupport::Notifications](#activesupportnotifications), and [StatsD](#statsd)).
+
+[↑ Back to features](#features)
+
+### ActiveSupport::Notifications
+
+Enable opt-in integration with `ActiveSupport::Notifications` for Rails and other ActiveSupport-based stacks:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.active_support_notifications = true
+end
+```
+
+Once enabled, SafeMemoize emits the following events through the standard notification pipeline:
+
+| Event | Fires when |
+|---|---|
+| `cache_hit.safe_memoize` | A cached value is returned |
+| `cache_miss.safe_memoize` | The method is called and no cached value exists |
+| `cache_store.safe_memoize` | A value is written to the cache (miss, `warm_memo`, or `load_memo`) |
+| `cache_evict.safe_memoize` | An entry is removed via `reset_memo`, `reset_all_memos`, or LRU eviction |
+| `cache_expire.safe_memoize` | An expired TTL entry is pruned |
+
+Each event payload includes:
+
+```ruby
+{
+  method: :method_name,   # Symbol
+  key:    cache_key,      # Array — the full cache key
+  class:  "ClassName"     # String — the host class name
+}
+```
+
+Subscribe to all SafeMemoize events via the standard ActiveSupport pattern:
+
+```ruby
+ActiveSupport::Notifications.subscribe(/\.safe_memoize$/) do |event|
+  Rails.logger.debug("[cache] #{event.name} #{event.payload[:class]}##{event.payload[:method]}")
+end
+```
+
+The integration is a no-op when ActiveSupport is not loaded — there is no overhead for non-Rails projects. `active_support_notifications` defaults to `false`.
+
+[↑ Back to features](#features)
+
+### StatsD
+
+Route cache lifecycle events to any StatsD-compatible client via `SafeMemoize::Adapters::StatsD`. Assign the client once in your initializer:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.statsd_client = Datadog::Statsd.new("localhost", 8125)
+end
+```
+
+SafeMemoize then calls `client.increment(metric, tags: [...])` on every cache event:
+
+| Metric | Fires when |
+|---|---|
+| `safe_memoize.hit` | A cached value is returned |
+| `safe_memoize.miss` | The method is called and no cached value exists |
+| `safe_memoize.store` | A value is written to the cache (miss, `warm_memo`, or `load_memo`) |
+| `safe_memoize.evict` | An entry is removed via `reset_memo`, `reset_all_memos`, or LRU eviction |
+| `safe_memoize.expire` | An expired TTL entry is pruned |
+
+Each call includes two tags: `method:method_name` and `class:ClassName`. The client must respond to `increment(metric, tags: [...])` — the interface used by `dogstatsd-ruby`, `statsd-instrument`, and most modern StatsD clients.
+
+If the client raises, the error is rescued and a warning is emitted to stderr rather than propagated to the caller. `statsd_client` defaults to `nil` (disabled).
+
+[↑ Back to features](#features)
+
+### OpenTelemetry
+
+`SafeMemoize::Adapters::OpenTelemetry` wraps the computation on each cache miss in an OpenTelemetry span, making memoized call costs visible in distributed traces. Assign a tracer once in your initializer:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.opentelemetry_tracer = OpenTelemetry.tracer_provider.tracer(
+    "safe_memoize",
+    SafeMemoize::VERSION
+  )
+end
+```
+
+SafeMemoize then wraps every cache miss (the actual method call, not cache hits) in a span named `"safe_memoize.compute"` with the following attributes:
+
+| Attribute | Value |
+|---|---|
+| `safe_memoize.method` | Name of the memoized method |
+| `safe_memoize.class` | Name of the host class |
+| `safe_memoize.cache_hit` | Always `false` — only misses are traced |
+
+Cache hits produce no spans, so tracing overhead is zero for cached calls. The adapter is compatible with any tracer that responds to `in_span(name, attributes:, &block)` — the interface provided by `opentelemetry-sdk`, `opentelemetry-api`, and no-op tracers alike. If `opentelemetry_tracer` is `nil` (the default), the adapter is completely bypassed.
+
+[↑ Back to features](#features)
+
+### Rails request-scope
+
+SafeMemoize ships optional Rails integration as a separate require (zero overhead in non-Rails apps):
+
+```ruby
+require "safe_memoize/rails"
+```
+
+#### Controller concern
+
+Include `SafeMemoize::Rails::RequestScoped` in any Rails controller that also `prepend SafeMemoize`. It automatically registers `after_action :reset_all_memos` so every instance memo is cleared at the end of each request — preventing state from leaking between requests when the controller object is reused:
+
+```ruby
+class ApplicationController < ActionController::Base
+  prepend SafeMemoize
+  include SafeMemoize::Rails::RequestScoped
+
+  memoize :current_user
+end
+```
+
+#### Service objects and non-controller classes
+
+In plain classes (service objects, Active Model objects), include `RequestScoped` to gain `reset_request_memos` and call it manually at the appropriate point:
+
+```ruby
+class ReportService
+  prepend SafeMemoize
+  include SafeMemoize::Rails::RequestScoped
+
+  def summary(id)
+    # ...
+  end
+  memoize :summary
+end
+
+svc = ReportService.new
+svc.summary(1)
+svc.reset_request_memos  # clears all instance memos
+```
+
+#### Middleware for tracked instances
+
+For service objects that should be reset automatically at request boundaries, use the Rack middleware together with `SafeMemoize::Rails.track`:
+
+```ruby
+# config/application.rb
+config.middleware.use SafeMemoize::Rails::Middleware
+```
+
+```ruby
+class ReportService
+  prepend SafeMemoize
+
+  def initialize
+    SafeMemoize::Rails.track(self)  # register for auto-reset
+  end
+
+  def summary(id)
+    # ...
+  end
+  memoize :summary
+end
+```
+
+`SafeMemoize::Rails::Middleware` calls `reset_all_memos` on every tracked instance in the current thread at the end of the request, even if the app raises. Tracking is thread-local, so concurrent requests never interfere. The tracked list is cleared automatically after each reset.
+
+[↑ Back to features](#features)
+
+### Deprecation
+
+SafeMemoize ships a structured deprecation helper for gem authors who build on top of it:
+
+```ruby
+SafeMemoize.deprecate(
+  "MyGem::OldHelper",
+  message: "Use MyGem::NewHelper instead",
+  horizon: "2.0.0"
+)
+# => [SafeMemoize] DEPRECATED: MyGem::OldHelper — Use MyGem::NewHelper instead (removal horizon: 2.0.0)
+```
+
+The warning is emitted to stderr by default. Configure a custom handler via `SafeMemoize.configure`:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.on_deprecation = ->(msg) { Rails.logger.warn(msg) }
+end
+```
+
+To raise on deprecation warnings in test environments:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.on_deprecation = ->(msg) { raise msg }
+end
+```
+
+[↑ Back to features](#features)
+
+## Ractor compatibility
+
+SafeMemoize is **not Ractor-compatible** in its current form. Passing a class that uses `memoize` into a `Ractor.new` block raises `RuntimeError: defined with an un-shareable Proc in a different Ractor`. There are two root causes:
+
+1. **Non-shareable closures.** `ClassMethods#memoize` builds anonymous modules using `define_method` with blocks that close over local variables (`ttl`, `max_size`, `condition`, `shared_mutex`, …). Ruby marks those Procs as non-Ractor-shareable, so the host class cannot be sent to a Ractor.
+
+2. **Mutable module-level state.** `SafeMemoize.configuration` reads `@configuration` from the `SafeMemoize` module — a mutable ivar on a shared constant — which raises `Ractor::IsolationError` from a non-main Ractor. This affects every memoized call because hooks and adapters always read the configuration.
+
+**Workaround:** Use Ruby Threads instead of Ractors — SafeMemoize is fully thread-safe via double-check locking and per-instance Mutexes. If you need true parallelism with Ractors, perform computation inside the Ractor without memoization and send frozen results back via `Ractor#send`.
+
+Ractor support is tracked in the v1.0.0 roadmap. The fix would require replacing closed-over variables with frozen shareable bindings and making `Configuration` a frozen value object, which is a significant redesign.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt.
 
+To run the benchmark suite: `bundle exec ruby benchmarks/benchmark.rb`.
+
+To generate API documentation locally: `bundle exec rake doc`. Output is written to `doc/` (gitignored). The online reference is published automatically to [RubyDoc.info](https://rubydoc.info/gems/safe_memoize) on every release. Install `memery` and `memo_wise` first if you want comparison columns against those gems.
+
 GitHub Actions also runs the full `bundle exec rake` suite automatically for pull requests, manual workflow runs, and pushes to `main` via `.github/workflows/ci.yml`.
 
 ## Releasing
@@ -568,9 +950,174 @@ To preview the changelog/version update without changing anything, use:
 bin/release 0.1.1 --dry-run
 ```
 
+## Public API and versioning guarantee
+
+From **v1.0.0** onwards SafeMemoize follows [Semantic Versioning](https://semver.org/). The table below declares every constant, method, and option key that forms the public contract. If you only call items listed here, you are guaranteed that:
+
+- **Patch** releases (1.x.**y**) contain bug fixes only — no behaviour changes.
+- **Minor** releases (1.**x**.0) add new features in a backwards-compatible way.
+- **Major** releases (**x**.0.0) may break the items below; a migration guide will be published for every such release.
+
+Anything **not** listed here — internal modules, private methods, `@__safe_memo_*__` ivars, the structure of the cache hash itself — is subject to change without notice in any release, including patch releases.
+
+### Top-level module
+
+| Symbol | Kind | Notes |
+|---|---|---|
+| `SafeMemoize::VERSION` | constant | Semver string, always present |
+| `SafeMemoize::Error` | class | Base error class (`< StandardError`) for rescuing any SafeMemoize-raised exception |
+| `SafeMemoize.configure { \|c\| … }` | module method | Yields `Configuration`; sets global defaults |
+| `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 |
+
+### `memoize` DSL (class method, added by `prepend SafeMemoize`)
+
+| Option key | Type | Default | Notes |
+|---|---|---|---|
+| `ttl:` | `Numeric \| nil` | `nil` | Seconds until entry expires |
+| `ttl_refresh:` | `Boolean` | `false` | Sliding window — resets clock on every hit |
+| `max_size:` | `Integer \| nil` | `nil` | LRU entry limit per method |
+| `if:` | `Symbol \| Proc \| nil` | `nil` | Store only when truthy |
+| `unless:` | `Symbol \| Proc \| nil` | `nil` | Store only when falsy |
+| `shared:` | `Boolean` | `false` | Class-level shared cache |
+| `key:` | `Proc \| nil` | `nil` | Class-level custom key generator |
+
+### `memoize_all` options (class method)
+
+All `memoize` option keys above, plus:
+
+| Option key | Type | Default |
+|---|---|---|
+| `except:` | `Array<Symbol>` | `[]` |
+| `only:` | `Array<Symbol>` | `[]` |
+| `include_protected:` | `Boolean` | `false` |
+| `include_private:` | `Boolean` | `false` |
+
+### Instance methods (public)
+
+**Inspection**
+
+| Method | Returns |
+|---|---|
+| `memoized?(method_name, *args, **kwargs)` | `Boolean` |
+| `memo_count(method_name = nil)` | `Integer` |
+| `memo_keys(method_name = nil)` | `Array` |
+| `memo_values(method_name = nil)` | `Array` |
+| `memo_inspect(method_name, *args, **kwargs)` | `Hash \| nil` |
+| `memo_ttl_remaining(method_name, *args, **kwargs)` | `Numeric \| nil` |
+| `memo_age(method_name, *args, **kwargs)` | `Numeric \| nil` |
+| `memo_stale?(method_name, *args, **kwargs)` | `Boolean` |
+
+**Invalidation and mutation**
+
+| Method | Returns |
+|---|---|
+| `reset_memo(method_name, *args, **kwargs)` | `nil` |
+| `reset_all_memos` | `nil` |
+| `memo_touch(method_name, *args, ttl: nil, **kwargs)` | `Boolean` |
+| `memo_refresh(method_name, *args, **kwargs)` | cached value |
+
+**Warm-up and persistence**
+
+| Method | Returns |
+|---|---|
+| `warm_memo(method_name, *args, ttl: nil, **kwargs)` | cached value |
+| `memo_preload(method_name, *arg_sets)` | `Array` |
+| `dump_memo(method_name = nil)` | `Hash` |
+| `load_memo(snapshot)` | `nil` |
+
+**Lifecycle hooks**
+
+| Method | Fires when |
+|---|---|
+| `on_memo_hit { \|key\| … }` | cache hit |
+| `on_memo_miss { \|key\| … }` | cache miss |
+| `on_memo_store { \|key, value\| … }` | value written |
+| `on_memo_expire { \|key\| … }` | TTL expires |
+| `on_memo_evict { \|key\| … }` | LRU eviction |
+| `clear_memo_hooks(hook_type = nil)` | — |
+
+**Metrics**
+
+| Method | Returns |
+|---|---|
+| `cache_stats` | `Hash` |
+| `cache_stats_for(method_name)` | `Hash` |
+| `cache_hit_rate` | `Float` |
+| `cache_miss_rate` | `Float` |
+| `cache_metrics_reset(method_name = nil)` | `nil` |
+
+**Custom keys**
+
+| Method | Notes |
+|---|---|
+| `memoize_with_custom_key(method_name) { \|*args, **kwargs\| … }` | Instance-level key generator |
+| `clear_custom_keys(method_name = nil)` | Remove one or all key generators |
+
+### Shared-cache class methods (added when any method uses `shared: true`)
+
+| Method | Returns |
+|---|---|
+| `reset_shared_memo(method_name, *args, **kwargs)` | `nil` |
+| `reset_all_shared_memos` | `nil` |
+| `shared_memoized?(method_name, *args, **kwargs)` | `Boolean` |
+| `shared_memo_count(method_name = nil)` | `Integer` |
+| `shared_memo_age(method_name, *args, **kwargs)` | `Numeric \| nil` |
+| `shared_memo_stale?(method_name, *args, **kwargs)` | `Boolean` |
+
+### `SafeMemoize::Configuration` attributes
+
+| Attribute | Type | Default |
+|---|---|---|
+| `default_ttl` | `Numeric \| nil` | `nil` |
+| `default_max_size` | `Integer \| nil` | `nil` |
+| `on_deprecation` | `Proc \| nil` | `nil` (writes to stderr) |
+| `on_hook_error` | `Proc \| nil` | `nil` (warns to stderr) |
+| `active_support_notifications` | `Boolean` | `false` |
+| `statsd_client` | `Object \| nil` | `nil` |
+| `opentelemetry_tracer` | `Object \| nil` | `nil` |
+
+### Opt-in extensions (not guaranteed until their owning milestone ships)
+
+The following are available now but reside under `require "safe_memoize/rails"` and are not covered by the v1.0.0 semver guarantee until the v1.x milestone that owns them is declared stable:
+
+- `SafeMemoize::Rails` module (`track`, `reset_tracked!`)
+- `SafeMemoize::Rails::RequestScoped` concern
+- `SafeMemoize::Rails::Middleware` Rack middleware
+- `SafeMemoize::Adapters::StatsD`
+- `SafeMemoize::Adapters::OpenTelemetry`
+
+## Ruby version support
+
+### Supported versions
+
+SafeMemoize requires **Ruby ≥ 3.3**. Every non-EOL Ruby version in the table below is actively tested in CI and receives bug-fix backports for critical issues.
+
+| Ruby | Status | EOL |
+|---|---|---|
+| 3.3 | Supported | Mar 2027 |
+| 3.4 | Supported | Mar 2028 |
+| 4.0 | Supported | ~ Dec 2028 |
+
+EOL dates follow the [Ruby maintenance schedule](https://www.ruby-lang.org/en/downloads/branches/).
+
+### Policy
+
+- **Dropping an EOL version is a minor-version change**, not a major one — it will appear in the CHANGELOG under `### Removed` and the gemspec `required_ruby_version` will be updated accordingly.
+- SafeMemoize targets the **current stable release plus the two previous non-EOL minors** at any given time. When Ruby releases a new version in December, CI gains a new column; when a version reaches EOL the next minor release removes it.
+- **No patch release will ever raise the minimum Ruby version.** Only `x.y.0` minor releases may do so.
+- Prerelease Rubies (dev / preview builds) are not officially supported but breakage is investigated on a best-effort basis.
+
+### History
+
+| Dropped in | Ruby version removed |
+|---|---|
+| v0.5.0 | Ruby 3.2 (reached EOL) |
+
 ## Roadmap
 
-See [ROADMAP.md](ROADMAP.md) for the planned path from v0.7.0 to v1.0.0 and beyond, including upcoming features, API stability goals, and the versioning policy.
+See [ROADMAP.md](ROADMAP.md) for the planned path to v1.0.0 and beyond, including upcoming features, API stability goals, and the versioning policy.
 
 ## Contributing