safe_memoize 0.7.0 → 0.9.0

data/README.md

@@ -1,5 +1,11 @@
 # SafeMemoize
 
+[![CI](https://github.com/eclectic-coding/safe_memoize/actions/workflows/ci.yml/badge.svg)](https://github.com/eclectic-coding/safe_memoize/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/safe_memoize)](https://rubygems.org/gems/safe_memoize)
+[![Total Downloads](https://img.shields.io/gem/dt/safe_memoize)](https://rubygems.org/gems/safe_memoize)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-CC342D)](https://www.ruby-lang.org)
+[![codecov](https://codecov.io/gh/eclectic-coding/safe_memoize/graph/badge.svg)](https://codecov.io/gh/eclectic-coding/safe_memoize)
+
 Thread-safe memoization for Ruby that correctly handles `nil` and `false` values.
 
 SafeMemoize is a production-ready, zero-dependency memoization library for Ruby. It wraps methods with a `prepend`-based cache that handles everything the standard `||=` idiom gets wrong: `nil` and `false` return values are cached correctly, per-argument result maps eliminate redundant computation for parameterized methods, and a per-instance `Mutex` with double-check locking makes the whole thing safe under concurrent load.
@@ -8,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
@@ -45,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
 
@@ -82,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:
@@ -103,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
@@ -117,6 +147,8 @@ class Config
 end
 ```
 
+[↑ Back to features](#features)
+
 ### Works with private methods
 
 ```ruby
@@ -136,6 +168,8 @@ class TokenProvider
 end
 ```
 
+[↑ Back to features](#features)
+
 ### Cache reset
 
 ```ruby
@@ -146,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.
@@ -182,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
@@ -194,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
@@ -209,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:
@@ -226,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:
@@ -259,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.
@@ -293,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:
@@ -342,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.
@@ -376,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.
@@ -388,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:
@@ -426,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
@@ -436,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
@@ -447,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
@@ -474,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
@@ -494,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.
@@ -515,18 +670,237 @@ 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)
+
 ## 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`. 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
@@ -562,6 +936,10 @@ To preview the changelog/version update without changing anything, use:
 bin/release 0.1.1 --dry-run
 ```
 
+## 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.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/eclectic-coding/safe_memoize.

data/ROADMAP.md

@@ -0,0 +1,92 @@
+# SafeMemoize Roadmap
+
+This document tracks the planned evolution of SafeMemoize through v1.0.0 and beyond. Items are grouped by release milestone; ordering within a milestone reflects priority, not a strict implementation sequence.
+
+---
+
+## v0.9.0 — Observability & Ecosystem Integration
+
+*Goal: make SafeMemoize a first-class citizen in Rails/ActiveSupport stacks and in observability pipelines.*
+
+| Feature | Description | Status |
+|---|---|---|
+| ActiveSupport::Notifications integration | Emit `cache.hit`, `cache.miss`, `cache.evict`, and `cache.expire` events when ActiveSupport is available (opt-in via configuration) | Shipped |
+| StatsD adapter | Thin optional module (`SafeMemoize::Adapters::StatsD`) that routes lifecycle hooks to a StatsD client with sensible metric names and tags | Shipped |
+| OpenTelemetry spans | Optional adapter (`SafeMemoize::Adapters::OpenTelemetry`) wrapping computation time in a trace span for distributed tracing pipelines | Shipped |
+| Rails request-scope helper | Guide + optional mixin for resetting instance memos at the end of each request (controller concern, middleware, or Active Model pattern) | Shipped |
+| Formal benchmark suite | `benchmarks/` directory with comparisons against `memery`, `memo_wise`, and raw `||=`, covering single-threaded throughput and contention under concurrent load | Shipped |
+| Concurrency stress tests | Dedicated spec suite hammering shared-cache paths and LRU eviction under high thread counts to surface race conditions | Shipped |
+
+---
+
+## v1.0.0 — Stable API
+
+*Goal: declare a stable, semver-governed public API that downstream code can depend on with confidence.*
+
+| Feature | Description | Status |
+|---|---|---|
+| Semantic versioning guarantee | Document which constants, methods, and option keys are public API; breaking changes require a major bump henceforth | Planned |
+| Complete RBS + Sorbet signatures | Cover all public methods including overloads for optional keyword arguments; publish `.rbi` stubs as a companion package if demand warrants | Planned |
+| Full API reference | Generated documentation hosted on RubyDoc or a dedicated docs site; all public methods documented with parameter types, return values, and usage examples | Planned |
+| Ractor compatibility audit | Investigate and either support Ractor-compatible operation (Mutex replacement, shared-cache storage) or document the limitation clearly | Planned |
+| Ruby version policy | Formalise the supported Ruby version window and cadence for dropping EOL versions | Planned |
+| Deprecation sweep | Resolve or formally deprecate any unstable internal APIs before the stable release | Planned |
+| Upgrade guide | Document all breaking changes from 0.x and provide a migration path for users of deprecated behaviour | Planned |
+
+---
+
+## v1.1.0 — Pluggable Cache Stores
+
+*Goal: allow the in-process hash cache to be swapped for an external store, enabling cross-process and distributed memoization.*
+
+| Feature | Description | Status |
+|---|---|---|
+| Cache store adapter interface | Define a minimal read/write/delete/clear/keys contract that external backends must implement | Planned |
+| `store:` option on `memoize` | Accept any store adapter object; defaults to the existing in-process hash store | Planned |
+| Redis adapter | Reference implementation (`SafeMemoize::Stores::Redis`) with TTL, LRU-like expiry, and serialization handled transparently | Planned |
+| Rails.cache adapter | Thin wrapper around `ActiveSupport::Cache::Store` for projects already using a configured Rails cache | Planned |
+| Global default store | Set via `SafeMemoize.configure` — applies a default store to every memoized method without per-call configuration | Planned |
+
+---
+
+## v1.2.0 — Async & Fiber-Safe Memoization
+
+*Goal: first-class support for Fiber-based concurrency frameworks (Async, Falcon, Rails async controllers).*
+
+| Feature | Description | Status |
+|---|---|---|
+| Fiber-local memoization mode | `memoize :method, fiber_local: true` stores results in `Fiber[:safe_memoize_cache]` rather than instance variables, giving each fiber its own isolated cache automatically reset when the fiber terminates | Planned |
+| Ractor-compatible shared cache | Revisit `shared: true` using `Ractor::TVar` or shareable frozen objects so class-level caches work across Ractors | Planned |
+| concurrent-ruby integration | Optional adapter using `Concurrent::Map` and `Concurrent::ReentrantReadWriteLock` as a drop-in replacement for `Mutex` where higher read-concurrency is desirable | 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 |
+
+---
+
+## Versioning policy
+
+SafeMemoize follows [Semantic Versioning](https://semver.org/) from v1.0.0 onwards:
+
+- **Patch** (1.x.**y**) — bug fixes; no API changes
+- **Minor** (1.**x**.0) — additive features; backward-compatible
+- **Major** (**x**.0.0) — breaking changes; migration guide published
+
+0.x releases may include breaking changes between minor versions.
+
+---
+
+## Contributing
+
+Ideas, bug reports, and pull requests are welcome. Open an issue at <https://github.com/eclectic-coding/safe_memoize/issues> to discuss a feature before building it. If you are picking up a roadmap item, mention the milestone in your PR so it can be tracked against this document.