retriable 4.2.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a551efb6db5acea9e82dde8e48afdea1869f6b93461a3c48c33f8385fbea6392
-  data.tar.gz: fbf6bb8c5ade48420e0f2a43532bafff0e4159eb4cf149bce559116ec1c91e50
+  metadata.gz: b1518899ae471b83e7167d0f2dce18e198a5069d30e6f05f04c0754ebd1c3b3a
+  data.tar.gz: 5fdd9babcd9dcb9dceeec99ce861018fd58435f50a184e62a64fa5142523d235
 SHA512:
-  metadata.gz: 19d5ac72e1614b7fdb3984697db76ad3f6ae2e9b1f60ff1eb470e210738cd67154afc2776b55329fca345fad6263035a41eb0748626f427fd2d05cc0bfea9c89
-  data.tar.gz: c1d46594742b7c19985a63037199125b718e6c6395dd8276013719d8c7f9cd64376637471b90fa9249869767da9a2474cafc31afd04f373f73249d8ebdfa0337
+  metadata.gz: af50822074d864951bc299bea96cb52ea5d35cbe7d5b0d079e5e633dec30cce8131a8db30339613562155015ee396a8fc7eb21ea841cf8beb0a826842ce314f0
+  data.tar.gz: d9dfa3ae45a889ee8326ba5aa7fb119af47302dc087e6c4a6b4033cbe0da9178ea41214b3fd5360f904b72f056ff709b5526c7298c2ff173d115803d88ca661e

data/AGENTS.md

@@ -0,0 +1,15 @@
+# Retriable
+
+## Agent skills
+
+### Issue tracker
+
+Issues live in GitHub Issues on `kamui/retriable`, via the `gh` CLI. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+The five canonical triage roles, using their default label strings. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: `CONTEXT.md` and `docs/adr/` at the repo root. See `docs/agents/domain.md`.

data/CHANGELOG.md

@@ -1,5 +1,58 @@
 # HEAD
 
+## 5.0.0
+
+**This is a major release with a breaking change. Please read carefully before
+upgrading.**
+
+### Breaking changes
+
+Retriable 5.0 makes the thread-safety change below. Because it changes direct
+config mutation, it is released as a major version.
+([#151](https://github.com/kamui/retriable/pull/151))
+
+The published config is frozen. Mutating `Retriable.config` directly
+raises `FrozenError`:
+
+```ruby
+Retriable.config.sleep_disabled = true # => FrozenError
+Retriable.config.contexts[:api] = {}   # => FrozenError
+```
+
+Go through `configure` instead:
+
+```ruby
+Retriable.configure { |c| c.sleep_disabled = true }
+```
+
+Check your test setup first: `Retriable.config.sleep_disabled = true` in a
+`spec_helper` or `rails_helper` is the likeliest place this bites. Reading
+`Retriable.config` is unaffected.
+
+A published config is shared by every thread reading it, so an in-place write
+was a data race that could corrupt another thread's retry behavior with no sign
+anything had gone wrong. Freezing it is what makes the copy-on-write guarantee
+below hold in practice rather than only on paper.
+
+The full upgrade guide lives in [docs/migration.md](docs/migration.md#4x-to-5x).
+
+### Bug fixes
+
+- `Retriable.configure` is now thread-safe. Configuration is copy-on-write: the
+  block mutates a duplicate, which is published atomically only if the block
+  returns without raising. Concurrent readers therefore see either the whole
+  previous config or the whole new one, never a half-applied mix, and a raising
+  block leaves the existing config in place. Nested mutable values (`on`,
+  `intervals`, `contexts`, and anything inside them) are deep-copied, so a
+  mutation inside a `configure` block can no longer reach back into the config
+  other threads are reading. `Retriable.with_context` now resolves the context
+  lookup and the global options against a single snapshot, closing a race where
+  a concurrent `configure` could drop a context's retry options. Nested
+  `configure` calls remain supported: they share the outer working copy and
+  publish once when the outermost block returns. See **Breaking changes** above
+  for the direct-mutation behavior change this required.
+  ([#151](https://github.com/kamui/retriable/pull/151))
+
 ## 4.2.0
 
 ### Bug fixes
@@ -77,7 +130,7 @@
 
 ### Breaking changes
 
-- Removed `timeout:` option. The `timeout:` option has been removed from `Retriable.retriable`, `Retriable.configure`, and `Retriable.with_override`. It was a thin wrapper around Ruby's `Timeout.timeout`, which has well-documented safety issues: it interrupts execution at arbitrary lines and can corrupt internal state in libraries that are not interrupt-safe (mutexes, file handles, network sockets, allocator state). This was first raised against this gem in [#96](https://github.com/kamui/retriable/issues/96) in 2021; Retriable 3.8.0 deprecated the option, and 4.0 removes the footgun entirely. As a side effect, the historical bug where Retriable's own internal `Timeout::Error` was silently retried by default is no longer reachable, since Retriable no longer raises a timeout itself. User-raised `Timeout::Error` (for example, from a `Timeout.timeout` block you write inside the retried block) is still matched by the default `on: [StandardError]` because `Timeout::Error < RuntimeError < StandardError`. Passing `timeout:` to `Retriable.retriable` or `Retriable.with_override` now raises `ArgumentError`; setting `config.timeout` in `Retriable.configure` now raises `NoMethodError` because the configuration attribute has been removed. See the [4.0 migration section in the README](README.md#migration-from-3x-to-40) for replacement patterns.
+- Removed `timeout:` option. The `timeout:` option has been removed from `Retriable.retriable`, `Retriable.configure`, and `Retriable.with_override`. It was a thin wrapper around Ruby's `Timeout.timeout`, which has well-documented safety issues: it interrupts execution at arbitrary lines and can corrupt internal state in libraries that are not interrupt-safe (mutexes, file handles, network sockets, allocator state). This was first raised against this gem in [#96](https://github.com/kamui/retriable/issues/96) in 2021; Retriable 3.8.0 deprecated the option, and 4.0 removes the footgun entirely. As a side effect, the historical bug where Retriable's own internal `Timeout::Error` was silently retried by default is no longer reachable, since Retriable no longer raises a timeout itself. User-raised `Timeout::Error` (for example, from a `Timeout.timeout` block you write inside the retried block) is still matched by the default `on: [StandardError]` because `Timeout::Error < RuntimeError < StandardError`. Passing `timeout:` to `Retriable.retriable` or `Retriable.with_override` now raises `ArgumentError`; setting `config.timeout` in `Retriable.configure` now raises `NoMethodError` because the configuration attribute has been removed. See the [4.0 migration guide](docs/migration.md#3x-to-40) for replacement patterns.
 - Minimum Ruby version is now 3.2. Support for Ruby 2.x, 3.0, and 3.1 has been dropped in Retriable 4.0. If you need Retriable on Ruby 2.3.0-3.1.x, the 3.8.x line (`~> 3.8`) remains available.
 
 ### Features

data/Gemfile

@@ -17,6 +17,8 @@ group :development do
 end
 
 group :development, :test do
+  # ostruct left the default gems in Ruby 3.5; pry still requires it.
+  gem "ostruct"
   gem "pry"
   gem "rake", "~> 13.0"
 end

data/README.md

@@ -7,7 +7,7 @@ Retriable is a simple DSL to retry failed code blocks with randomized [exponenti
 ## Table of Contents
 
 - [Requirements](#requirements)
-- [Migration from 3.x to 4.0](#migration-from-3x-to-40)
+- [Upgrading](#upgrading)
 - [Installation](#installation)
 - [Usage](#usage)
   - [Defaults](#defaults)
@@ -42,37 +42,19 @@ If you need Ruby 1.9.3 support, use the [2.x branch](https://github.com/kamui/re
 
 If you need Ruby 1.8.x to 1.9.2 support, use the [1.x branch](https://github.com/kamui/retriable/tree/1.x) by specifying `~1.4` in your Gemfile.
 
-## Migration from 3.x to 4.0
+## Upgrading
 
-### Ruby version
+Retriable 5.0 changes one thing for existing users: `Retriable.config` is now a
+frozen snapshot, so direct writes raise `FrozenError`.
 
-Retriable 4.0 requires Ruby 3.2 or later. If you run Ruby 2.3.0-3.1.x, or want to stay on the 3.x gem line, use Retriable 3.8.x by specifying `~> 3.8` in your Gemfile.
-
-### `timeout:` option removed
-
-The `timeout:` option was deprecated in Retriable 3.8.0 and has been removed in Retriable 4.0. It was a thin wrapper around `Timeout.timeout`, which has well-documented safety issues: it interrupts execution at arbitrary lines and can corrupt internal state in libraries that are not interrupt-safe. See [issue #96](https://github.com/kamui/retriable/issues/96) for the original report of this problem.
-
-If you previously used `Retriable.retriable(timeout: 5) { ... }`, you have two recommended alternatives:
-
-1. **Use your library's native timeout** (preferred). For example, configure `Net::HTTP#read_timeout`, Faraday's `request.timeout`, or your database client's statement timeout. Library-native timeouts do not have the safety issues of `Timeout.timeout`.
-
-2. **Manage the timeout yourself inside the block** if no native option exists:
-
-   ```ruby
-   require "timeout"
-
-   Retriable.retriable do
-     Timeout.timeout(5) do
-       # code here...
-     end
-   end
-   ```
-
-   **Note:** This still uses `Timeout.timeout`, which has the same safety issues that motivated removing the option — interruption can happen at any line, including inside non-interrupt-safe library code (mutexes, file handles, network sockets, allocator state). Prefer option 1 wherever possible. For background, see [why Ruby's `Timeout` is dangerous](https://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/), [Headius on Thread#raise and Timeout](http://blog.headius.com/2008/02/ruby-threadraise-threadkill-timeoutrb.html), [In Ruby, don't use `Timeout`](https://adamhooper.medium.com/in-ruby-dont-use-timeout-77d9d4e5a001), and [Timeout: Ruby's most dangerous API](https://www.mikeperham.com/2015/05/08/timeout-rubys-most-dangerous-api/).
-
-   Like the removed `timeout:` option, `Timeout.timeout(5)` inside the block is per-try — each retry gets a fresh 5-second budget. For an overall cap across all retries, use `max_elapsed_time:` instead.
+```ruby
+Retriable.config.sleep_disabled = true              # => FrozenError
+Retriable.configure { |c| c.sleep_disabled = true } # do this instead
+```
 
-Passing `timeout:` to `Retriable.retriable` or `Retriable.with_override` now raises `ArgumentError`. The `timeout` configuration attribute has also been removed, so `Retriable.configure { |c| c.timeout = 5 }` now raises `NoMethodError`.
+Test setup files such as `spec_helper` and `rails_helper` are the likeliest
+place this bites. For the full 4.x to 5.x and 3.x to 4.0 guides, see
+[docs/migration.md](docs/migration.md).
 
 ## Installation
 
@@ -91,7 +73,7 @@ require 'retriable'
 In your Gemfile:
 
 ```ruby
-gem 'retriable', '~> 4.0'
+gem 'retriable', '~> 5.0'
 ```
 
 ## Usage
@@ -138,20 +120,20 @@ The default interval table with 10 tries looks like this (in seconds, rounded to
 
 Here are the available options, in some vague order of relevance to most common use patterns:
 
-| Option                 | Default           | Definition                                                                                                                                                                                                                                                        |
-| ---------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`tries`**            | `3`               | Number of attempts to make at running your code block (includes initial attempt). Pass `Float::INFINITY` to keep retrying until success or until `max_elapsed_time` is reached.                                                                                   |
-| **`on`**               | `[StandardError]` | Type of exceptions to retry. [Read more](#configuring-which-options-to-retry-with-on).                                                                                                                                                                            |
-| **`retry_if`**         | `nil`             | Callable (for example a `Proc` or lambda) that receives the rescued exception and returns true/false to decide whether to retry. [Read more](#advanced-retry-matching-with-retry_if).                                                                             |
-| **`on_retry`**         | `nil`             | `Proc` to call after each try is rescued. Pass `false` to disable a callback set in `#configure` for a single call. [Read more](#callbacks).                                                                                                                      |
-| **`on_give_up`**       | `nil`             | `Proc` to call when Retriable stops retrying after a rescued retriable exception. [Read more](#callbacks).                                                                                                                                                        |
-| **`sleep_disabled`**   | `false`           | When true, disable exponential backoff and attempt retries immediately.                                                                                                                                                                                           |
-| **`base_interval`**    | `0.5`             | The initial interval in seconds between tries.                                                                                                                                                                                                                    |
-| **`max_elapsed_time`** | `900` (15 min)    | The maximum amount of total time in seconds that code is allowed to keep being retried. Set to `nil` to disable the time limit and retry based solely on `tries`.                                                                                                 |
-| **`max_interval`**     | `60`              | The maximum interval in seconds that any individual retry can reach.                                                                                                                                                                                              |
-| **`multiplier`**       | `1.5`             | Each successive interval grows by this factor. A multipler of 1.5 means the next interval will be 1.5x the current interval.                                                                                                                                      |
-| **`rand_factor`**      | `0.5`             | The percentage to randomize the next retry interval time. The next interval calculation is `randomized_interval = retry_interval * (random value in range [1 - randomization_factor, 1 + randomization_factor])`                                                  |
-| **`intervals`**        | `nil`             | Skip generated intervals and provide your own array of intervals in seconds. [Read more](#custom-interval-array).                                                                                                                                                 |
+| Option                 | Default           | Definition                                                                                                                                                                                                       |
+| ---------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`tries`**            | `3`               | Number of attempts to make at running your code block (includes initial attempt). Pass `Float::INFINITY` to keep retrying until success or until `max_elapsed_time` is reached.                                  |
+| **`on`**               | `[StandardError]` | Type of exceptions to retry. [Read more](#configuring-which-options-to-retry-with-on).                                                                                                                           |
+| **`retry_if`**         | `nil`             | Callable (for example a `Proc` or lambda) that receives the rescued exception and returns true/false to decide whether to retry. [Read more](#advanced-retry-matching-with-retry_if).                            |
+| **`on_retry`**         | `nil`             | `Proc` to call after each try is rescued. Pass `false` to disable a callback set in `#configure` for a single call. [Read more](#callbacks).                                                                     |
+| **`on_give_up`**       | `nil`             | `Proc` to call when Retriable stops retrying after a rescued retriable exception. [Read more](#callbacks).                                                                                                       |
+| **`sleep_disabled`**   | `false`           | When true, disable exponential backoff and attempt retries immediately.                                                                                                                                          |
+| **`base_interval`**    | `0.5`             | The initial interval in seconds between tries.                                                                                                                                                                   |
+| **`max_elapsed_time`** | `900` (15 min)    | The maximum amount of total time in seconds that code is allowed to keep being retried. Set to `nil` to disable the time limit and retry based solely on `tries`.                                                |
+| **`max_interval`**     | `60`              | The maximum interval in seconds that any individual retry can reach.                                                                                                                                             |
+| **`multiplier`**       | `1.5`             | Each successive interval grows by this factor. A multipler of 1.5 means the next interval will be 1.5x the current interval.                                                                                     |
+| **`rand_factor`**      | `0.5`             | The percentage to randomize the next retry interval time. The next interval calculation is `randomized_interval = retry_interval * (random value in range [1 - randomization_factor, 1 + randomization_factor])` |
+| **`intervals`**        | `nil`             | Skip generated intervals and provide your own array of intervals in seconds. [Read more](#custom-interval-array).                                                                                                |
 
 Timing options are validated before retrying. `tries` must be a positive integer when Retriable generates intervals, or `Float::INFINITY` for unbounded retries. `base_interval`, `max_interval`, `multiplier`, and `max_elapsed_time` must be non-negative numbers, with `max_elapsed_time` also accepting `nil`. `rand_factor` must be a number from `0` through `1`. If provided, `intervals` must be an array of non-negative numbers; because it replaces generated intervals, it also overrides `tries`, `base_interval`, `max_interval`, `rand_factor`, and `multiplier` validation. `intervals` cannot be combined with `tries: Float::INFINITY`.
 
@@ -211,6 +193,50 @@ When a higher-precedence layer sets `tries:` without `intervals:`, it clears any
 if `intervals` was configured). Within a single call, passing `intervals:` still
 overrides `tries:`.
 
+#### Thread safety
+
+`#configure` is the only supported way to change configuration, and it is safe to
+call from multiple threads.
+
+Configuration is copy-on-write. `#configure` duplicates the current config, hands
+your block the copy, and publishes it only if the block returns without raising.
+So a reader in another thread always sees either the whole previous config or the
+whole new one, never a half-applied mix, and a block that raises leaves the
+existing config in place.
+
+Configuration blocks are serialized. Keep them short, and do not wait inside one
+for work that may call `#configure`, because that work cannot begin until the
+current block returns. Readers are unaffected and continue using the last
+published config while a block runs.
+
+The published config is deeply frozen. Reaching around `#configure` to mutate it
+raises `FrozenError`:
+
+```ruby
+Retriable.config.tries = 5              # => FrozenError
+Retriable.config.contexts[:api] = {}    # => FrozenError
+
+Retriable.configure { |c| c.tries = 5 } # this is the supported path
+```
+
+That is deliberate. A published config is shared by every thread reading it, so an
+in-place write is a data race that used to corrupt other threads' retry behavior
+silently. `Retriable.config` remains fine to **read**.
+
+Two more details:
+
+- `#configure` calls can nest. Nested calls on the configuring thread, including
+  calls from its fibers, share the outer working copy. Only the outermost call
+  publishes. If its block raises, none of the nested changes are published. A
+  nested call does not create an independent commit or savepoint.
+- Inside a `#configure` block, every fiber on the configuring thread sees the
+  in-progress config. Other threads keep seeing the last published one until the
+  block completes.
+
+Thread safety covers the config structure. User-supplied callbacks such as
+`retry_if`, `on_retry`, and `on_give_up` can still hold mutable state. The caller
+must synchronize that state if the callback can run from multiple threads.
+
 ### Override
 
 `#with_override` is a block-scoped API for forcing retry options that should

data/benchmark/config_publication.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "rbconfig"
+require "retriable"
+
+RUN_SECONDS = Float(ENV.fetch("RETRIABLE_BENCH_SECONDS", "1.0"))
+THREAD_COUNTS = ENV.fetch("RETRIABLE_BENCH_THREADS", "1,2,4,8")
+                   .split(",")
+                   .map { |value| Integer(value, 10) }
+                   .uniq
+                   .freeze
+BATCH_SIZE = 100
+
+raise ArgumentError, "RETRIABLE_BENCH_SECONDS must be positive" unless RUN_SECONDS.positive?
+raise ArgumentError, "RETRIABLE_BENCH_THREADS must contain positive integers" unless THREAD_COUNTS.all?(&:positive?)
+
+SnapshotHolder = Struct.new(:value)
+snapshot_holder = SnapshotHolder.new(Retriable.config)
+
+BENCHMARK_CASES = {
+  "plain_snapshot_read" => -> { snapshot_holder.value },
+  "published_config_read" => -> { Retriable.config },
+  "successful_retriable" => -> { Retriable.retriable { nil } }
+}.freeze
+
+def monotonic_time
+  Process.clock_gettime(Process::CLOCK_MONOTONIC)
+end
+
+def measure(operation, thread_count)
+  ready = Queue.new
+  start = Queue.new
+  threads = Array.new(thread_count) do
+    Thread.new do
+      ready << true
+      start.pop
+      count = 0
+      deadline = monotonic_time + RUN_SECONDS
+
+      loop do
+        BATCH_SIZE.times { operation.call }
+        count += BATCH_SIZE
+        break if monotonic_time >= deadline
+      end
+
+      count
+    end
+  end
+
+  thread_count.times { ready.pop }
+  started_at = monotonic_time
+  thread_count.times { start << true }
+  operation_count = threads.sum(&:value)
+  elapsed = monotonic_time - started_at
+
+  operation_count / elapsed
+end
+
+BENCHMARK_CASES.each_value do |operation|
+  5_000.times { operation.call }
+end
+
+puts "ruby=#{RUBY_DESCRIPTION}"
+puts "engine=#{RUBY_ENGINE}"
+puts "host_cpu=#{RbConfig::CONFIG.fetch("host_cpu")}"
+puts "seconds_per_case=#{RUN_SECONDS}"
+puts "case,threads,operations_per_second"
+
+BENCHMARK_CASES.each do |name, operation|
+  THREAD_COUNTS.each do |thread_count|
+    operations_per_second = measure(operation, thread_count)
+    puts format(
+      "%<name>s,%<threads>d,%<operations>d",
+      name: name, threads: thread_count, operations: operations_per_second.round,
+    )
+  end
+end

data/docs/adr/0001-copy-on-write-config-publication.md

@@ -0,0 +1,124 @@
+# 1. Copy-on-write config publication
+
+## Status
+
+Accepted.
+
+## Context
+
+`Retriable.config` is a single mutable object read on every `Retriable.retriable`
+call and written rarely, usually once at boot. That shape had three races:
+
+- `@config ||= Config.new` was check-then-act, so two threads booting at once
+  could build two different `Config` objects.
+- `retriable` read attributes off the live shared config one at a time, so a
+  concurrent `configure` could hand a single call an inconsistent mix of old and
+  new values.
+- `with_context` read the config more than once. The existence check and the
+  option resolution could straddle a `configure`. The check could pass against
+  the old snapshot before resolution silently dropped the context's retry
+  options from the new one.
+
+Reads vastly outnumber writes, so a scheme that keeps readers cheap and pays the
+cost on the writer is the right trade.
+
+## Decision
+
+Configuration is copy-on-write.
+
+`configure` takes `CONFIG_MUTEX`, duplicates the published config, yields the
+duplicate, and publishes it only if the block returns without raising. Writers
+serialize against each other; a raising block leaves the previous config in
+place. Publication does not change the method's return contract: `configure`
+returns the block's result, not the candidate or published snapshot.
+
+**One publication seam, one engine path.** `CONFIG_PUBLICATION_MUTEX` guards the
+`@config` reference and is held only for a reference read or the publishing
+write, never across the user's block, so a writer blocks a reader for no longer
+than a pointer swap. We do not special-case MRI. An unsynchronized read would be
+safe there thanks to the GVL, but it would leave a second memory model to
+maintain for JRuby and TruffleRuby.
+
+The mutex is part of the hot path. A `retriable` call with no local options or
+override uses the published `Config` directly, so it does not otherwise pay for
+`Config.new`, `to_h`, or a merge. `benchmark/config_publication.rb` measures both
+raw config reads and successful retry calls with one or more reader threads. We
+accept the mutex cost for a portable memory-visibility guarantee, but we do not
+assume that cost is free. If the benchmark shows material contention on a
+supported engine, `Concurrent::AtomicReference` is the preferred alternative.
+An engine-conditional unsynchronized read is not.
+
+**The published snapshot is deeply frozen.** Atomic publication alone does not
+deliver a consistent read: if the published object stays mutable, any caller can
+still do `Retriable.config.contexts[:api][:tries] = 1` and corrupt what every
+other thread is reading. `Config#freeze` therefore freezes `on`, `intervals` and
+`contexts` recursively before freezing the config itself. `configure` publishes a
+*copy* of the candidate so freezing never reaches a container the caller still
+owns (`c.on = my_array` must not leave `my_array` frozen).
+
+**`dup` copies containers, not leaves, and never preserves frozen state.**
+`Config#initialize_copy` deep-copies `on`, `intervals` and `contexts`; scalars,
+procs, exception classes and regexps are shared by reference. A Hash's mutable
+default *value* is part of the copied graph, because a shared one would let
+`config.contexts[:absent] << x` reach the caller's object; a `default_proc`
+remains a shared callable leaf. Copies start from `#dup` rather than a fresh
+literal so a container's class and a Hash's default behavior survive. Rebuilding
+into a bare `{}` would silently downgrade an indifferent-access `contexts` hash
+and break string-key lookups. Frozen state is deliberately dropped, because a dup
+is the mutable working copy a `configure` block mutates; publication re-freezes
+it.
+
+Hash *keys* are left as-is. Ruby already dups and freezes an unfrozen String key
+on assignment. The supported key types, Symbols for `contexts` and exception
+classes for `on`, are immutable. Copying keys would buy immutability only for
+container keys, still miss arbitrary mutable objects, and break `compare_by_identity`
+lookups, so the boundary stays where Ruby puts it.
+
+Deep immutability covers the containers owned by `Config`. Callable leaves can
+hold their own mutable state, and a shared `default_proc` can mutate state outside
+the config. Callers remain responsible for synchronizing that state when the
+callable runs from multiple threads.
+
+**Two mechanisms, two questions.** A thread-local (`CONFIGURING_THREAD_KEY`)
+answers "is this thread mid-`configure`?", which is what lets the configuring
+thread and its fibers see their own candidate. Which snapshot a *single*
+`retriable`/`with_context` call resolves against is a different question,
+answered by passing that snapshot as an argument to `retriable_with_config`. A
+thread-local would leak the resolved snapshot across the caller's block and
+change what `Retriable.config` returns inside it, so the two are kept apart. The
+snapshot travels one hop; `with_context` resolves its contexts hash once and
+passes that.
+
+**Nested calls join the outer transaction.** A nested `configure` sees the
+candidate stored in `CONFIGURING_THREAD_KEY` and yields that same object without
+taking `CONFIG_MUTEX` again. This preserves the behavior supported before
+copy-on-write and avoids recursive locking. The outermost block alone publishes.
+If it raises, Retriable discards every change made by nested blocks. A nested call
+does not create an independent commit or savepoint. Fibers on the configuring
+thread share the transaction because `CONFIGURING_THREAD_KEY` is a true thread
+local.
+
+## Consequences
+
+- Direct mutation of `Retriable.config` now raises `FrozenError`. This is a
+  breaking change for code that reached around `configure`; the migration is to
+  use `configure`. Reading `Retriable.config` is unaffected. This change will
+  ship in Retriable 5.0.
+- Nested `configure` remains supported. Nested blocks mutate the outer working
+  copy and do not publish separately.
+- Writer blocks are serialized for their full duration. A block must not wait
+  for work that may call `configure`, because that work cannot acquire
+  `CONFIG_MUTEX` until the current block returns. Readers do not take that mutex
+  and continue using the last published snapshot.
+- `configure` pays two deep copies per call (one to build the candidate, one to
+  take ownership before freezing). `configure` is a rare, usually boot-time
+  operation, so this is not on any hot path.
+- Every `retriable` call takes one uncontended mutex to read the config
+  reference. The checked-in benchmark measures the cost on CRuby and JRuby. A
+  measured optimization may replace the publication mechanism, but it must keep
+  one memory model across supported engines.
+- The structural snapshot is thread-safe. User-supplied callbacks and other
+  callable leaves must synchronize their own mutable state.
+- `Retriable.config` is still a global. This ADR makes the global safe to read
+  concurrently; it does not introduce per-thread, per-instance, or Ractor-safe
+  configuration.

data/docs/agents/domain.md

@@ -0,0 +1,38 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+This repo is **single-context**: one `CONTEXT.md` and one `docs/adr/` at the root.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-copy-on-write-config.md
+│   └── 0002-randomized-exponential-backoff.md
+├── lib/
+└── spec/
+```
+
+Design decisions belong in `docs/adr/` with a numbered filename. Don't scatter them into other `docs/` subdirectories.
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_

data/docs/agents/issue-tracker.md

@@ -0,0 +1,45 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues on `kamui/retriable`. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me`, the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

data/docs/agents/triage-labels.md

@@ -0,0 +1,17 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.
+
+None of these labels exist in `kamui/retriable` yet. Create one on first use with `gh label create <name>`; the repo's existing labels (`question`, `dependencies`, `ruby`) don't collide with any of them.