safe_memoize 0.9.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b47b6031a8f395991376eec0407b93d1cf02caecad23f4d77e4d68234ef87b5
-  data.tar.gz: 7542678912a0a39425a75e3addfc718f2abb35068e28e0cdc0444c294dd4c4c1
+  metadata.gz: 6beffd3f5a1de6f8582c9a164502f353b8ac6c55caec6326edb4c52b0bf913ec
+  data.tar.gz: 44ebaf0f89254c692b9d33d8962577c9644df6d910818905e46395ba5e28cf89
 SHA512:
-  metadata.gz: a304040bf86b1bc359c91f3d687a9f45e020bdaddded53b82a87e473553491aa9daba1ac45f8abadffb8ede8af270479f73762ab47357486aef9b46043afacde
-  data.tar.gz: 79d6a552f98f9f2ef1482832c211cc7b0a58f6481c989320c19db63b870a1723b482304955a133c661a0082a07c17de539258a9f869da0b5cbd0aaa2acacd96a
+  metadata.gz: 0f22cd22816499ec3400a7b98cf51c3a3b77a43a0e26451ff97d6f01877d02df8772b7b3be0209e86b5c6c00d435bc96e7db8fd3a28619169e1f0e97b8ab0263
+  data.tar.gz: af315893620e46fe419a2a61ff4092f7d27f71bbfe98185ba0714162148c7d19b2d31ed9db3909d500f3e12f474f51d66ec027d81cd2d7e9948e4bc388d3a5db

data/.yardopts

@@ -0,0 +1,10 @@
+--markup markdown
+--output-dir doc/
+--main README.md
+--files CHANGELOG.md,ROADMAP.md
+--no-private
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md
+ROADMAP.md

data/CHANGELOG.md

@@ -8,6 +8,18 @@ from v1.0.0 onwards. Prior 0.x releases may include breaking changes between min
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-05-22
+
+### Added
+
+- Ractor compatibility audit — `spec/ractor_spec.rb` documents the specific failure modes (non-shareable closures in `define_method` blocks, `Ractor::IsolationError` on `SafeMemoize.configuration`); README section explains the limitation and the Thread-based workaround
+- Semantic versioning guarantee — README `## Public API and versioning guarantee` section enumerates every public constant, method, option key, and `Configuration` attribute covered by semver from v1.0.0 onwards; opt-in extensions (`SafeMemoize::Rails`, `SafeMemoize::Adapters::*`) are explicitly called out as not yet covered until their owning milestone ships
+- Full API reference — YARD documentation added to all public methods, classes, and modules; `SafeMemoize::Adapters::StatsD` and `SafeMemoize::Adapters::OpenTelemetry` fully documented with usage examples; internal modules marked `@api private`; `.yardopts` and `rake doc` task added; `gem "yard"` added as a development dependency
+- Deprecation sweep — pre-v1.0.0 API consistency audit: `memoized?`, `memo_ttl_remaining`, `memo_touch`, `memo_age`, `memo_stale?` now use `compute_cache_key` instead of `safe_memo_cache_key` so they correctly resolve entries stored with a custom key (instance-level `memoize_with_custom_key` or class-level `key:`); `memo_matcher_for` (used by `reset_memo` and `memo_refresh`) receives the same fix; `SafeMemoize::Error` added to the public API guarantee table and to RBS + Sorbet signatures; RBS and `.rbi` `warm_memo` block annotation corrected back to mandatory (was incorrectly marked optional in v0.9.0 signatures)
+- Ruby version policy — README `## Ruby version support` section formalises the supported version window (Ruby ≥ 3.3; current stable plus two previous non-EOL minors), the cadence for dropping EOL versions (minor release only, never a patch), and a history table of dropped versions; CI matrix documents covered versions with their EOL dates
+- Complete RBS + Sorbet signatures — `sig/safe_memoize.rbs` corrected: `SafeMemoize::Adapters::StatsD` added; `memo_count`, `memo_keys`, `memo_values` fixed from rest-arg to proper optional single arg; `clear_memo_hooks` and `clear_custom_keys` optional-arg annotations corrected; `warm_memo` block marked optional; new `rbi/safe_memoize.rbi` ships Sorbet stubs covering the full public API, all `Configuration` attributes, adapters, and opt-in Rails helpers
+- Upgrade guide — `UPGRADING.md` documents every breaking change introduced across the 0.x series, with before/after code examples and migration steps for each; covers Ruby 3.2 removal, TTL clock change, `memo_keys`/`memo_values` shape change, `memoize` definition-time raise, argument mutation fix, hook exception isolation, and the two custom-key introspection fixes landing in v1.0.0
+
 ## [0.9.0] - 2026-05-22
 
 ### Added

data/README.md

@@ -895,11 +895,25 @@ 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`. Install `memery` and `memo_wise` first if you want comparison columns against those gems.
+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`.
 
@@ -936,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
 

data/ROADMAP.md

@@ -4,34 +4,19 @@ This document tracks the planned evolution of SafeMemoize through v1.0.0 and bey
 
 ---
 
-## 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 |
+| Semantic versioning guarantee | Document which constants, methods, and option keys are public API; breaking changes require a major bump henceforth | Shipped |
+| Complete RBS + Sorbet signatures | Cover all public methods including overloads for optional keyword arguments; publish `.rbi` stubs as a companion package if demand warrants | Shipped |
+| 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 | Shipped |
+| Ractor compatibility audit | Investigate and either support Ractor-compatible operation (Mutex replacement, shared-cache storage) or document the limitation clearly | Shipped |
+| Ruby version policy | Formalise the supported Ruby version window and cadence for dropping EOL versions | Shipped |
+| Deprecation sweep | Resolve or formally deprecate any unstable internal APIs before the stable release | Shipped |
+| Upgrade guide | Document all breaking changes from 0.x and provide a migration path for users of deprecated behaviour | Shipped |
 
 ---
 

data/Rakefile

@@ -7,4 +7,9 @@ RSpec::Core::RakeTask.new(:spec)
 
 require "standard/rake"
 
+require "yard"
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.options = ["--fail-on-warning"]
+end
+
 task default: %i[spec standard]

data/UPGRADING.md

@@ -0,0 +1,197 @@
+# Upgrading to SafeMemoize 1.0.0
+
+This guide covers every behavioral change introduced across the 0.x series that could affect code written against an earlier release. Work through the sections that apply to your starting version.
+
+---
+
+## Summary of breaking changes
+
+| Change | Introduced | Impact |
+|---|---|---|
+| Ruby 3.2 dropped | v0.5.0 | High if still on Ruby 3.2 |
+| TTL clock starts at first call, not definition | v0.6.0 | Medium — affects TTL precision |
+| `memo_keys`/`memo_values` shape for custom keys | v0.6.1 | Low — only if inspecting key metadata |
+| `memoize` raises at definition time for undefined methods | v0.8.0 | Medium — affects dynamic class construction |
+| Argument mutation no longer corrupts cache | v0.8.0 | Low — was silent bug; may surface latent test issues |
+| Hook exceptions no longer propagate | v0.8.0 | Medium — only if catching hook exceptions |
+| `memoized?` / introspection methods now respect custom keys | v1.0.0 | Low — bug fix; only if using custom keys |
+| `reset_memo` with args and `memo_refresh` respect custom keys | v1.0.0 | Low — bug fix; only if using custom keys |
+
+---
+
+## Upgrading from 0.1.x or 0.2.x
+
+Follow every section below in order.
+
+## Upgrading from 0.3.x – 0.4.x
+
+Follow sections starting from [Ruby 3.2 dropped](#ruby-32-dropped-v050).
+
+## Upgrading from 0.5.x
+
+Follow sections starting from [TTL clock fix](#ttl-clock-now-starts-at-first-call-v060).
+
+## Upgrading from 0.6.x
+
+Follow sections starting from [memoize on undefined methods](#memoize-on-an-undefined-method-raises-at-definition-time-v080).
+
+## Upgrading from 0.7.x – 0.9.x
+
+Follow sections starting from [custom key introspection fix](#introspection-methods-now-respect-custom-keys-v100).
+
+---
+
+## Ruby 3.2 dropped (v0.5.0)
+
+**Impact:** High — the gem will not install on Ruby 3.2.
+
+Ruby 3.2 reached end-of-life and was removed from the supported matrix in v0.5.0. The gemspec now enforces `ruby >= 3.3.0`.
+
+**Migration:** Upgrade to Ruby 3.3 or later before updating the gem.
+
+---
+
+## TTL clock now starts at first call, not definition (v0.6.0)
+
+**Impact:** Medium — affects how long entries actually live in the cache.
+
+Before v0.6.0, the TTL countdown began when `memoize :method, ttl: N` was evaluated (class load time). If a class was loaded 30 seconds before the first call, entries would expire 30 seconds earlier than expected.
+
+From v0.6.0 onwards, the clock starts on the first cache write — the entry lives for exactly `ttl` seconds after it is populated.
+
+**Migration:** No code change required. Entries now live for the duration you specified. If you intentionally set very short TTLs and relied on the early-start behaviour (unlikely), reduce your TTL value accordingly.
+
+---
+
+## `memo_keys`/`memo_values` shape change for custom-keyed entries (v0.6.1)
+
+**Impact:** Low — only affects code that reads the hashes returned by these methods.
+
+Before v0.6.1, entries stored via `memoize_with_custom_key` were surfaced in `memo_keys` and `memo_values` as:
+
+```ruby
+{ args: <the_custom_key>, kwargs: nil }
+```
+
+From v0.6.1 onwards they are correctly surfaced as:
+
+```ruby
+{ custom_key: <the_custom_key> }
+```
+
+**Migration:** If your code inspects the hash returned by `memo_keys` or `memo_values` and checks for an `:args` key to detect custom-keyed entries, update it to check for `:custom_key` instead:
+
+```ruby
+# Before
+entry[:args] # custom key was smuggled here
+
+# After
+entry[:custom_key] # explicit field
+entry[:args]       # only present for default-keyed entries
+```
+
+---
+
+## `memoize` on an undefined method raises at definition time (v0.8.0)
+
+**Impact:** Medium — affects any code that calls `memoize` before the method is defined,
+or that dynamically defines methods after `memoize` is called.
+
+Before v0.8.0, calling `memoize :missing_method` silently succeeded at class load time. The error only appeared at runtime when the memoized wrapper tried to call `super` and found nothing to call.
+
+From v0.8.0 onwards, `memoize` raises `ArgumentError` immediately if the named method does not exist at the time of the call.
+
+**Migration:** Ensure `memoize` is always called *after* the method it wraps:
+
+```ruby
+# Wrong — memoize called before def (raises ArgumentError in v0.8.0+)
+memoize :compute
+def compute = expensive_work
+
+# Correct
+def compute = expensive_work
+memoize :compute
+```
+
+If you use `Module#prepend` or `include` to add methods dynamically, make sure `memoize` is called after the module is prepended/included:
+
+```ruby
+include MyMethods   # defines :compute
+memoize :compute    # now safe
+```
+
+---
+
+## Argument mutation no longer corrupts the cache (v0.8.0)
+
+**Impact:** Low — this was a silent bug. Existing code is unlikely to rely on it, but test suites that mutate arguments after a call and expect a cache miss may need updating.
+
+Before v0.8.0, mutable cache keys (arrays, hashes, strings passed as arguments) were stored by reference. Mutating an argument after a call could cause the cache to behave unpredictably — sometimes missing on identical arguments, sometimes returning stale values.
+
+From v0.8.0 onwards, argument arrays, hashes, and strings are deep-frozen into an independent copy when the cache key is built. Callers can mutate their arguments after a call without affecting the cache.
+
+**Migration:** No migration required for production code. If a test mutates arguments after a memoized call and expects a cache miss, the test was relying on the buggy behaviour — update it to use distinct argument values instead.
+
+---
+
+## Hook exceptions no longer propagate to callers (v0.8.0)
+
+**Impact:** Medium — only affects code that wraps memoized calls in `rescue` to catch errors raised by hooks.
+
+Before v0.8.0, an exception raised inside an `on_memo_hit`, `on_memo_miss`, `on_memo_store`, `on_memo_expire`, or `on_memo_evict` hook would propagate through the memoized method call and be visible to the caller.
+
+From v0.8.0 onwards, hook exceptions are isolated. By default a `[SafeMemoize] Hook error in <type>: <message>` warning is written to `$stderr` and execution continues normally.
+
+**Migration:** If you need hook exceptions to propagate (e.g. in a strict test environment), configure `on_hook_error` to re-raise:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.on_hook_error = ->(error, hook_type, cache_key) { raise error }
+end
+```
+
+Or to route them to your error tracker without raising:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.on_hook_error = ->(error, _type, _key) { Bugsnag.notify(error) }
+end
+```
+
+---
+
+## Introspection methods now respect custom keys (v1.0.0)
+
+**Impact:** Low — only affects code that uses `memoize_with_custom_key` or the `key:` option together with any of the introspection methods listed below.
+
+Before v1.0.0, the following methods looked up cache entries using the *default* key (derived from raw arguments) rather than the *custom* key generator. This meant they always returned incorrect results when a custom key was active:
+
+- `memoized?`
+- `memo_ttl_remaining`
+- `memo_touch`
+- `memo_age`
+- `memo_stale?`
+
+From v1.0.0 onwards, all five methods correctly call `compute_cache_key`, which checks for a custom key generator first.
+
+**Migration:** No code change required — the methods now return correct results. If your code had workarounds that bypassed these methods (e.g. manually inspecting `memo_keys` to determine if an entry existed), you can simplify them to use `memoized?` directly.
+
+---
+
+## `reset_memo` with args and `memo_refresh` respect custom keys (v1.0.0)
+
+**Impact:** Low — only affects code that uses custom keys and calls `reset_memo` with specific arguments, or calls `memo_refresh`.
+
+Before v1.0.0, `reset_memo(:method, *args)` with explicit arguments built a default key from raw args to match entries. When the method used a custom key generator, no entry was found and nothing was cleared. `memo_refresh` inherited the same flaw — the old entry survived and `refresh` returned the cached (stale) value instead of recomputing.
+
+From v1.0.0 onwards, both methods resolve the cache key through `compute_cache_key`.
+
+**Migration:** No code change required — the methods now behave correctly. Note that `reset_memo(:method)` with *no* arguments still clears all entries for the method regardless of key format; this behaviour is unchanged.
+
+---
+
+## New stable API
+
+All symbols listed in the README `## Public API and versioning guarantee` section are now covered by [Semantic Versioning](https://semver.org/) from v1.0.0 onwards. Breaking changes to any of those symbols require a major version bump.
+
+Opt-in extensions (`SafeMemoize::Rails`, `SafeMemoize::Adapters::StatsD`, `SafeMemoize::Adapters::OpenTelemetry`) are available but are *not* included in the v1.0.0 semver guarantee; they will be stabilised in a subsequent minor release.

data/lib/safe_memoize/adapters/opentelemetry.rb

@@ -1,10 +1,35 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # Optional adapters for external observability systems.
+  # None are auto-required; load them explicitly when needed.
   module Adapters
+    # Optional OpenTelemetry adapter.
+    #
+    # Wraps each cache-miss computation in an OpenTelemetry span so the time
+    # spent computing uncached values is visible in distributed traces.
+    #
+    # Configure via {Configuration#opentelemetry_tracer}:
+    #
+    #   SafeMemoize.configure do |c|
+    #     c.opentelemetry_tracer = OpenTelemetry.tracer_provider.tracer("safe_memoize")
+    #   end
+    #
+    # Each span is named {SPAN_NAME} and carries the attributes
+    # +safe_memoize.method+, +safe_memoize.class+, and +safe_memoize.cache_hit+.
+    # Falls back to untraced execution when no tracer is configured or the tracer
+    # does not respond to +#in_span+.
     module OpenTelemetry
+      # The name given to every span created by this adapter.
       SPAN_NAME = "safe_memoize.compute"
 
+      # Wraps the block in a span if a tracer is available; otherwise yields directly.
+      #
+      # @param tracer [Object, nil] an object responding to +#in_span+
+      # @param method_name [Symbol, String]
+      # @param class_name [String, nil]
+      # @yield the computation block (cache-miss path)
+      # @return [Object] the result of the block
       def self.trace(tracer, method_name, class_name)
         return yield unless tracer&.respond_to?(:in_span)
 

data/lib/safe_memoize/adapters/statsd.rb

@@ -2,7 +2,31 @@
 
 module SafeMemoize
   module Adapters
+    # Optional StatsD adapter.
+    #
+    # Routes SafeMemoize lifecycle events to any StatsD-compatible client
+    # (any object that responds to +#increment+).
+    #
+    # Configure via {Configuration#statsd_client}:
+    #
+    #   SafeMemoize.configure do |c|
+    #     c.statsd_client = Datadog::Statsd.new
+    #   end
+    #
+    # Emitted metrics:
+    #
+    # | Metric | Fires on |
+    # |---|---|
+    # | +safe_memoize.hit+ | cache hit |
+    # | +safe_memoize.miss+ | cache miss |
+    # | +safe_memoize.store+ | value written |
+    # | +safe_memoize.evict+ | LRU eviction |
+    # | +safe_memoize.expire+ | TTL expiration |
+    #
+    # Every metric is tagged with +method:<name>+ and +class:<name>+.
+    # Client errors are rescued and warned rather than raised.
     module StatsD
+      # @api private
       METRIC_NAMES = {
         on_hit: "safe_memoize.hit",
         on_miss: "safe_memoize.miss",
@@ -11,6 +35,13 @@ module SafeMemoize
         on_store: "safe_memoize.store"
       }.freeze
 
+      # Dispatches a lifecycle event to the StatsD client.
+      #
+      # @param client [Object] a StatsD-compatible client responding to +#increment+
+      # @param hook_type [Symbol] one of the keys in {METRIC_NAMES}
+      # @param cache_key [Array] the internal cache key (first element is the method name)
+      # @param class_name [String, nil]
+      # @return [void]
       def self.dispatch(client, hook_type, cache_key, class_name)
         metric = METRIC_NAMES[hook_type]
         return unless metric

data/lib/safe_memoize/cache_metrics_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module CacheMetricsMethods
     private
 

data/lib/safe_memoize/cache_record_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module CacheRecordMethods
     private
 

data/lib/safe_memoize/cache_store_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module CacheStoreMethods
     private