redis_queued_locks 1.16.2 → 1.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d49a1559431c569e92cfc1a9b56bd04d9942002aa6d79efcb533370f58b0c184
-  data.tar.gz: bc8fd235df24386a92275273de91d34804452eb085bbb5a2b7118eb4508319ab
+  metadata.gz: de70554e8788c12aaa830c8eca99f7b31f936836a3f664498299d213ba2b6036
+  data.tar.gz: fa8bc015bb930d9ccef934ab6884dd1ef930cf2b540a98ab221f78b1a06afac8
 SHA512:
-  metadata.gz: 0e7d0944406f13a7a6bac3e59153998fca9731e184ef5da83d8d415af7185f61a4b260166895d3858c501f4ae93cf160fb6b4c5c33e248d2aa82c9bac2265216
-  data.tar.gz: 8aff1a1fb28cbc510edc30efbab0eed49bbb088feff6235959b314b24d705e0058c6d1a347356874fa2a4b930f7aaba62e7f6b48bebf2622e11600998055f719
+  metadata.gz: e7ca083df52b3e53878512da62a8a515fe0bdf94f58d14e4d62db6facf1684b481597d5618f3d46294051774f0a2f076d7d518c0b848eedaefef0fca22158bd9
+  data.tar.gz: 1d3e8c5660334ef5925ad951408d262922a4786dce98d539ad9318edce240b9ffa47093d1a1fffa2fb8dc431f7be8d2ed6d0fe565d53743e5f5177b5750c42b6

data/.claude/project-overview.md

@@ -0,0 +1,205 @@
+# redis_queued_locks: Project Overview
+
+Ruby gem providing **distributed locks on Redis with a prioritized lock-acquisition queue**.
+Each lock has its own request queue; requests are processed FIFO (`:queued`) or first-come
+(`:random`). Requests have TTLs (with requeue), so queues never get stuck. Includes reentrancy
+(conflict) strategies, timed locks, retries/fail-fast, logging, instrumentation with sampling,
+and a background "swarm" that detects dead hosts and flushes their locks.
+
+- Repo: https://github.com/0exp/redis_queued_locks (MIT); main branch `master`
+- Runtime dependency: `redis-client ~> 0.20` (locked 0.30.1), nothing else
+- Ruby `>= 4.0` (`.ruby-version` = 4.0.7)
+
+---
+
+## 1. Architecture
+
+```
+RedisQueuedLocks (lib/redis_queued_locks.rb)   entry point; requires all parts; extends Debugger::Interface
+        │
+        ▼
+Client (client.rb)                              public API facade
+  ├── Config (config.rb + config/dsl.rb)        declarative settings + validators
+  ├── Swarm  (swarm.rb + swarm/*)               supervised background workers
+  └── Acquirer::* modules                       one stateless module per operation
+              │
+              ▼
+        RedisClient (redis-client gem)          WATCH/MULTI, Lua (EVAL), ZSET, HASH, SCAN
+```
+
+`Client.new(redis_client) { |config| ... }`:
+1. builds `Config` from the block,
+2. computes `uniq_identity` via `config['uniq_identifier']`,
+3. creates `Swarm` and starts it when `config['swarm.auto_swarm']` is true.
+
+Every other public method is a thin wrapper: it fills option defaults from `config[...]` and calls
+an `Acquirer::*` module function with `redis_client`.
+
+### Client → implementation map
+
+| Client method | Implementation |
+|---|---|
+| `lock` / `lock!` | `acquirer/acquire_lock.rb` + `acquirer/acquire_lock/*` |
+| `lock_series` / `lock_series!` | `acquirer/lock_series_poc.rb` (proof of concept) |
+| `unlock` | `acquirer/release_lock.rb` |
+| `extend_lock_ttl` | `acquirer/extend_lock_ttl.rb` |
+| `locked?` / `queued?` | `acquirer/is_locked.rb` / `acquirer/is_queued.rb` |
+| `lock_info` / `queue_info` | `acquirer/lock_info.rb` / `acquirer/queue_info.rb` |
+| `locks`, `locks_info`, `queues`, `queues_info`, `keys` | `acquirer/locks.rb`, `queues.rb`, `keys.rb` (SCAN-based) |
+| `clear_locks` | `acquirer/release_all_locks.rb` |
+| `clear_locks_of`, `clear_current_locks` | `acquirer/release_locks_of.rb` |
+| `clear_dead_requests` | `acquirer/clear_dead_requests.rb` |
+| `current_acquirer_id`, `current_host_id`, `possible_host_ids` | `resource.rb` |
+| `swarmize!`, `deswarmize!`, `swarm_status`, `swarm_info`, `probe_hosts`, `flush_zombies`, `zombie_locks`, `zombie_acquirers`, `zombie_hosts`, `zombies_info` | `swarm.rb` + `swarm/*` |
+
+### Lock acquisition flow (`acquirer/acquire_lock.rb` + `acquire_lock/`)
+
+`AcquireLock` is assembled from mixins (`extend`):
+
+| Mixin | Role |
+|---|---|
+| `TryToLock` (`try_to_lock.rb`) | One attempt: `ZADD NX` acquirer into the lock queue (timestamp score), then `multi(watch: [lock_key])` and take the lock if allowed (head of queue for `:queued`, any position for `:random`). Handles reentrant conflicts; TTL extension via inline Lua (`PTTL` + `PEXPIRE`). |
+| `WithAcqTimeout` | Global acquisition timeout (`timeout`). |
+| `DelayExecution` | Retry delay + jitter between attempts. |
+| `DequeueFromLockQueue` | Removes the acquirer from the queue on timeout/failure. |
+| `YieldExpire` | Runs the user block (optionally `timed`), then releases/expires the lock. |
+| `LogVisitor` / `InstrVisitor` | One method per lifecycle event for logs and instrumentation. |
+
+### Main `lock` options (defaults from config)
+
+`ttl`, `queue_ttl`, `timeout`, `timed`, `retry_count`, `retry_delay`, `retry_jitter`,
+`raise_errors`, `fail_fast`, `conflict_strategy`, `access_strategy`, `read_write_mode`
+(default `:write`; its doc is unfinished), `identity`, `meta`, `logger`, `log_lock_try`,
+`instrumenter`, `instrument`, log/instr sampling options, `log_sample_this`, `instr_sample_this`.
+
+- `access_strategy`: `:queued` (FIFO, default) or `:random`.
+- `conflict_strategy` (same process re-acquires its own lock): `:wait_for_lock` (default),
+  `:work_through`, `:extendable_work_through`, `:dead_locking`.
+
+### Redis data layout (`resource.rb`)
+
+| Key | Type | Purpose |
+|---|---|---|
+| `rql:lock:<name>` | HASH | lock owner + metadata (e.g. `l_spc_ts`, `l_spc_ext_ts` for reentrant cases) |
+| `rql:lock_queue:<name>` | ZSET | acquirer queue scored by enqueue time |
+| `rql:lock_queue:<name>:read` / `:write` | ZSET | read/write mode queues |
+| `rql:swarm:hsts` | HASH | swarm host heartbeats |
+
+- Acquirer ID: `rql:acq:<pid>/<thread>/<fiber>/<ractor>/<identity>`
+- Host ID: `rql:hst:<pid>/<thread>/<ractor>/<identity>` (no fiber)
+
+### Instrumentation events
+
+`redis_queued_locks.` + `lock_obtained`, `reentrant_lock_obtained`,
+`extendable_reentrant_lock_obtained`, `lock_hold_and_release`, `reentrant_lock_hold_completes`,
+`lock_series_obtained`, `lock_series_hold_and_release`, `explicit_lock_release`,
+`explicit_all_locks_release`, `release_locks_of`.
+
+### Errors (`errors.rb`)
+
+Base `RedisQueuedLocks::Error < StandardError`, plus `ArgumentError`, `LockAlreadyObtainedError`,
+`LockAcquirementTimeoutError`, `LockAcquirementRetryLimitError`, `TimedLockTimeoutError`,
+`ConflictLockObtainError`, `SwarmError`, `SwarmArgumentError`, `ConfigError`
+(`ConfigNotFoundError`, `ConfigValidationError`). Internal `*IntermediateTimeoutError`s
+inherit from `Timeout::Error`.
+
+---
+
+## 2. Architecture patterns by module
+
+| Module | Patterns |
+|---|---|
+| `Client` | Facade; constructor injection (caller-supplied `RedisClient`); `x` returns a result hash, `x!` raises |
+| `Acquirer::*` | One module per command; stateless `class << self` functions; uniform `{ ok:, result: }` returns (public API contract; swarm element internals use bare scalars/primitives) |
+| `AcquireLock` | Composition via `extend` mixins; optimistic concurrency (WATCH/MULTI) + Lua for atomic updates; strategy options (`access_strategy`, `conflict_strategy`) |
+| Log/Instr visitors | Visitor-style event hooks keep observability out of the algorithm; percent sampling via `sampling_happened?(percent)` |
+| `Logging` / `Instrument` | Null Object defaults (`VoidLogger`, `VoidNotifier`); Adapter (`instrument/active_support.rb`); duck typing (`::Logger` API, `#notify(event, payload)`) |
+| `Config` | Declarative DSL: `setting(key, default)` and `validate(key) { }` registries; access as `config['a.b']`; runtime `Client#configure` |
+| `Swarm` | Template base classes `SwarmElement::Threaded` (Thread) and `SwarmElement::Isolated` (Ractor; commands/replies via a per-element pair of `Ractor::Port`s, termination via `Ractor#monitor`). `ProbeHosts < Threaded`; `FlushZombies < Isolated` with its own connection from `RedisClientBuilder` (plain, pooled or sentinel). `Supervisor` watchdog thread restarts dead elements. |
+| `Resource` | Single source of truth for key names and identity strings |
+| Misc | `Data < Hash` result object; `Utilities::Lock` mutex wrapper; global `Debugger` toggle |
+
+---
+
+## 3. Configuration (`config.rb`)
+
+| Group | Keys (default) |
+|---|---|
+| Retry/timeouts | `retry_count` (3), `retry_delay` (200 ms), `retry_jitter` (25 ms), `try_to_lock_timeout` (10 s), `is_timed_by_default` (false) |
+| TTLs | `default_lock_ttl` (5000 ms), `default_queue_ttl` (15 s), `dead_request_ttl` (1 day, ms) |
+| Strategies | `default_conflict_strategy` (`:wait_for_lock`), `default_access_strategy` (`:queued`) |
+| Batching | `lock_release_batch_size` (100), `clear_locks_of__lock_scan_size` / `__queue_scan_size` (300), `key_extraction_batch_size` (500) |
+| Identity | `uniq_identifier` (lambda → `Resource.calc_uniq_identity`) |
+| Logging | `logger` (VoidLogger), `log_lock_try`, `log_sampling_enabled`, `log_sampling_percent` (15), `log_sampler` |
+| Instrumentation | `instrumenter` (VoidNotifier), `instr_sampling_enabled`, `instr_sampling_percent` (15), `instr_sampler` |
+| Errors | `detailed_acq_timeout_error` (false) |
+| Swarm | `swarm.auto_swarm` (false), `swarm.supervisor.liveness_probing_period` (2 s), `swarm.probe_hosts.*` (enabled, `probe_period` 2 s, `redis_config.*`), `swarm.flush_zombies.*` (enabled, `zombie_ttl` 15000 ms, scan sizes 500, `zombie_flush_period` 10, `redis_config.*`) |
+
+---
+
+## 4. Directory map
+
+```
+lib/redis_queued_locks.rb          entry point
+lib/redis_queued_locks/
+  client.rb                        public API
+  config.rb, config/dsl.rb         settings DSL + defaults
+  acquirer/*.rb                    one operation per file
+  acquirer/acquire_lock/*          lock algorithm mixins + visitors
+  swarm.rb, swarm/*                supervisor, swarm elements, zombie logic, redis client builder
+  logging/, instrument/            void defaults, samplers, ActiveSupport adapter
+  resource.rb                      keys and identities
+  data.rb, errors.rb, utilities.rb, utilities/lock.rb, debugger/, version.rb
+sig/                               RBS mirror of lib/ + sig/vendor stubs (redis_client, active_support, semantic_logger)
+spec/                              redis_queued_locks_spec.rb (~2.6k lines, integration), spec_helper.rb, setup_simplecov.rb
+.github/workflows/                 tests, lint, typecheck-static, typecheck-runtime
+bin/console, bin/setup             dev scripts
+Rakefile, Steepfile, rbs_collection.yaml
+```
+
+Known quirk: `sig/redis_queued_locks/acquier.rbs` is misspelled (should be `acquirer.rbs`).
+
+---
+
+## 5. Technology stack
+
+### Runtime
+- Ruby >= 4.0; stdlib `timeout`, `securerandom`, `logger`; Thread, Fiber, Ractor, Mutex
+- Redis server: WATCH/MULTI, EVAL (Lua), ZSET, HASH, PTTL/PEXPIRE, SCAN
+- `redis-client ~> 0.20`
+- Optional, duck-typed: any `::Logger`-compatible logger; any `#notify(event, payload)` instrumenter (ActiveSupport adapter included; SemanticLogger has only an RBS stub)
+
+### Test / development
+- RSpec 3.13: random order, no monkey patching, `expect` syntax, `Thread.abort_on_exception = true`
+- rspec-retry 0.6.2: 5 retries per example (marked temporary)
+- A real Redis is required (CI: `supercharge/redis-github-action@1.8.1`)
+- SimpleCov 1.3.2: line + branch coverage, HTML report; 100% minimum disabled (TODO)
+- RBS 4.2 + `rbs collection` + tsort; Steep 2.1 (static); RBS runtime testing via `rbs/test/setup`
+- RuboCop 1.91 through `armitage-rubocop`, in two separate runs so Ruby cops (and their rubydex project index, `AllCops/UseProjectIndex`) never see RBS files:
+  - `.rubocop.yml`: Ruby sources (general, rake, rspec presets; plugins rubocop-rspec, -performance, -rake, -thread_safety); several Metrics cops disabled
+  - `.rubocop.rbs.yml`: RBS cops only (rbs preset, plugin rubocop-on-rbs, no project index): `RBS/*` on `sig/**/*.rbs` and `RBSInline/*` on inline annotations in `lib/**/*.rb`; Ruby cop departments are excluded explicitly because inline `# rubocop:enable` directives would re-enable them despite `DisabledByDefault`
+- rake, bundler, pry, pry-doc, reline, activesupport 8.1
+
+### Rake tasks
+`rspec` (default), `rubocop` (runs `rubocop:ruby` and `rubocop:rbs`, fails if either fails), `steep:check`, plus bundler gem tasks (`build`, `release`, ...).
+
+### CI (GitHub Actions, ubuntu-latest, Ruby 4.0, on every push)
+
+| Workflow | Command |
+|---|---|
+| tests | `bundle exec rake rspec` (with a Redis service) |
+| lint | `bundle exec rake rubocop` |
+| typecheck-static | `bundle exec rbs collection install && bundle exec rake steep:check -j 10` |
+| typecheck-runtime | `RBS_TEST_RAISE=true RUBYOPT='-rrbs/test/setup' RBS_TEST_OPT='-I sig' RBS_TEST_TARGET='RedisQueuedLocks::*' bundle exec rspec --failure-exit-code=0` (never fails the build) |
+
+---
+
+## 6. Conventions
+
+- `# frozen_string_literal: true` in every Ruby file.
+- YARD tags on every class/method: `@api public|private`, `@since`, `@version` (bump `@version` when changing behavior).
+- Every `lib/` change gets a matching `sig/` RBS update; use `# steep:ignore` only where Steep can't infer types.
+- New operation: new `Acquirer::*` module, thin `Client` method (+ `!` variant if it should raise), RBS, spec.
+- New config option: `setting` (+ `validate`) in `config.rb`, read via `config['key']`, document defaults.
+- Development gems go in `Gemfile` (`Gemspec/DevelopmentDependencies: Gemfile`), not the gemspec.
+- Temporary debt: rspec-retry, disabled coverage minimum, runtime type-check job that can't fail.

data/.claude/rules/acquirer.md

@@ -0,0 +1,61 @@
+---
+paths:
+  - "lib/redis_queued_locks/acquirer.rb"
+  - "lib/redis_queued_locks/acquirer/**/*.rb"
+---
+
+# Acquirer modules (`lib/redis_queued_locks/acquirer/**`)
+
+## Observed style and patterns
+- **Module shape**: `module RedisQueuedLocks::Acquirer::<CamelName>` in `acquirer/<snake_name>.rb`, `# @api private`, a single public entry function inside `class << self` named after the file (`ReleaseLock.release_lock`, `IsLocked.locked?`), helpers under `private` in the same `class << self`.
+- **Utilities**: modules that time or instrument `extend RedisQueuedLocks::Utilities` (gives `clock_gettime`, `run_non_critical`).
+- **Signatures** (see `arguments.md` for the design rationale):
+  - Read-only queries: few positional args `(redis_client, lock_name)`; collection queries use keywords `(redis_client, scan_size:, with_info:)`.
+  - Mutating operations: long positional lists ending with the fixed observability tail
+    `logger, instrumenter, instrument, log_sampling_enabled, log_sampling_percent, log_sampler, log_sample_this, instr_sampling_enabled, instr_sampling_percent, instr_sampler, instr_sample_this`
+    (order of `logger`/`instrumenter` varies between modules; check the existing signature).
+  - Only `AcquireLock.acquire_lock` uses keyword args (`process_id:`, `thread_id:`, ...).
+- **Two-layer mutating operations** (`release_lock`, `release_all_locks`, `release_locks_of`):
+  1. `rel_start_time = clock_gettime`
+  2. call a private `fully_*` helper returning `{ ok:, result: }` and destructure it: `fully_x(...) => { ok:, result: }`
+  3. `time_at = Time.now.to_f`; `rel_time = ((rel_end_time - rel_start_time) / 1_000.0).ceil(2)` (microseconds → ms)
+  4. `instr_sampled = RedisQueuedLocks::Instrument.should_instrument?(...)`
+  5. `run_non_critical { instrumenter.notify('redis_queued_locks.<event>', { at:, rel_time:, ... }) } if instr_sampled`
+  6. return `{ ok: true, result: { ..., rel_time: } }`
+- **Results**: always `{ ok: Boolean, result: ... }` for operations; `result` is a Symbol status (`:ttl_extended`, `:async_expire_or_no_lock`, `:released`, `:nothing_to_release`) or a Symbol-keyed Hash with abbreviated keys (`rel_key_cnt`, `tch_queue_cnt`, `rel_time`). Info queries return a String-keyed Hash / Set or `nil` when absent.
+- **Redis access**:
+  - Keys only via `Resource.prepare_lock_key` / `prepare_lock_queue` and `Resource::*_PATTERN`.
+  - Raw commands: `redis.call('CMD', ...)` with uppercase string command names and string args (`'0'`, `'-inf'`, `'+inf'`).
+  - Pooled connection: wrap multi-command work in `redis.with do |rconn| ... end`.
+  - Atomic writes: `rconn.multi do |transact| ... end` (or `multi(watch: [lock_key])` in `TryToLock`); batch reads: `pipelined do |pipeline| ... end` then index `result[0]`, `result[1]` into named vars (`hget_cmd_res`, `pttl_cmd_res`).
+  - Iteration: `scan('MATCH', PATTERN, count: scan_size) { |key| ... }`, collecting into `Set.new.tap { |set| ... }`; deletes are batched by scan size.
+  - Lua: frozen heredoc constant (`<<~LUA_SCRIPT.strip.tr("\n", '').freeze`) + `call('EVAL', SCRIPT, 1, key, arg)`.
+  - Release = `EXPIRE key 0` / `ZREMRANGEBYSCORE queue -inf +inf`; Redis TTL sentinels handled explicitly (`PTTL` `-2` = missing, `-1` = no expiry → `Float::INFINITY`).
+- **Data normalization**: Redis hash strings are converted with `Float(...)` / `Integer(...)` inside `hget_cmd_res.tap do |lock_data| ... end`, optional fields guarded with `if lock_data['x']`.
+- **AcquireLock**:
+  - Main module `require_relative`s its parts, then `extend`s the mixins (`TryToLock`, `DelayExecution`, `YieldExpire`, `WithAcqTimeout`, `DequeueFromLockQueue`); mixins are plain modules with instance methods (`def try_to_lock(...)`), visitors are `class << self` modules called explicitly (see `visitors.md`).
+  - The algorithm is a numbered step script (`# Step 0`, `# Step 2.1`, `# Step 2.2.a`) driven by a mutable `acq_process` hash (`:should_try`, `:tries`, `:acquired`, `:result`, `:lock_info`, timings).
+  - Failure modes are Symbols (`:fail_fast_no_try`, `:fail_fast_after_try`, `:conflict_dead_lock`, ...); exceptions are raised only when `raise_errors` is true, with a message naming the lock key / acquirer id.
+  - Timing via monotonic `clock_gettime` (microseconds); wall time only for `at:`/`ts` fields.
+- **Inline typing**: `# @type var result: Symbol`, `{} #: Hash[String,String|Float|Integer]`, and `# steep:ignore` on pattern-matching destructures and splats (`rconn.call('DEL', *keys) # steep:ignore`).
+
+## Claude rules
+1. New operation: create `acquirer/<snake_name>.rb` with `module RedisQueuedLocks::Acquirer::<CamelName>`, one public `class << self` entry function named after the file, private helpers below `private`; add `require_relative` to `acquirer.rb` and a mirrored `sig/redis_queued_locks/acquirer/<snake_name>.rbs`.
+2. Read-only query → small positional args or `scan_size:` / `with_info:` keywords, return data or `nil`. Mutating operation → follow the two-layer pattern (public timing/instrumentation wrapper + private `fully_*` helper).
+3. Keep the observability tail parameters in the established order of the closest sibling module; pass them through unchanged from `Client`.
+4. Return `{ ok:, result: }`; use Symbol statuses for simple outcomes and abbreviated Symbol keys (`rel_*`, `*_cnt`, `*_time`) consistent with existing results. Don't raise from acquirer modules except through the `raise_errors` path in `AcquireLock`.
+5. Use `redis.with { |rconn| ... }` for any multi-command work; use `multi` for writes that must be atomic, `pipelined` for independent reads, `multi(watch:)` or Lua when a write depends on a read.
+6. Use uppercase string Redis commands and string numeric args; handle `PTTL`/`TTL` sentinel values explicitly.
+7. Iterate keys with `scan('MATCH', Resource::*_PATTERN, count:)`, never `KEYS`; batch deletes by scan size.
+8. Measure durations with `clock_gettime` and report ms with `/ 1_000.0).ceil(2)`; use `Time.now.to_f` only for event timestamps.
+9. Wrap every `instrumenter.notify` / logger call in `run_non_critical` (or a visitor) and gate it with `Instrument.should_instrument?` / `Logging.should_log?`; observability must never break locking.
+10. In `AcquireLock`, add behavior as a new step or mixin rather than growing `acquire_lock`; keep the `# Step N.x` comment numbering, update `acq_process` keys consistently, and add a matching `LogVisitor`/`InstrVisitor` method for each new lifecycle event.
+11. When normalizing lock hash fields, follow the `Float()` / `Integer()` conversion pattern; if a new lock field is added, update both `lock_info.rb` and `locks.rb` (they duplicate the formatting).
+
+## Recommendations (proposed, not yet project policy)
+Apply to new or touched code; don't refactor existing code for these unless asked.
+1. Load Lua scripts once (`SCRIPT LOAD` + `EVALSHA`, falling back to `EVAL` on `NOSCRIPT`), as the TODO in `extend_lock_ttl.rb` asks.
+2. Prefer indexed lookups over full `SCAN` loops for new features (see TODOs in `release_locks_of.rb`, `locks.rb`, `queues.rb`).
+3. Treat `lock_series_poc.rb` as experimental: don't build new features on it without asking.
+4. Extract the duplicated lock-hash normalization in `lock_info.rb` / `locks.rb` and queue formatting in `queue_info.rb` / `queues.rb` into shared helpers (their TODOs ask for this).
+5. Unify the observability tail order (`logger, instrumenter` vs `instrumenter, logger` in `release_lock`) when those signatures are next changed.

data/.claude/rules/arguments.md

@@ -0,0 +1,59 @@
+---
+paths:
+  - "lib/redis_queued_locks/client.rb"
+  - "lib/redis_queued_locks/acquirer/**/*.rb"
+  - "lib/redis_queued_locks/swarm.rb"
+  - "lib/redis_queued_locks/config.rb"
+  - "sig/redis_queued_locks/client.rbs"
+  - "sig/redis_queued_locks/acquirer/**/*.rbs"
+---
+
+# Long explicit keyword lists (core API design principle)
+
+## The pattern
+The public API and the lock pipeline use **long, flat, explicit argument lists**: every tunable is a named keyword with its default declared directly in the signature (usually `config['...']`), and every value is forwarded explicitly, name by name, through each layer:
+
+```ruby
+# Client (public DSL surface)
+def lock(lock_name, ttl: config['default_lock_ttl'], queue_ttl: config['default_queue_ttl'],
+         ..., instr_sample_this: false, &block)
+  RedisQueuedLocks::Acquirer::AcquireLock.acquire_lock(
+    redis_client, lock_name,
+    process_id: RedisQueuedLocks::Resource.get_process_id, ...,
+    ttl:, queue_ttl:, ..., instr_sample_this:, &block
+  )
+end
+```
+
+This is a deliberate framework-level decision, **not** something to refactor into parameter objects, option hashes, context structs or builders.
+
+## Why (framework-engineering rationale)
+- **Minimal object allocation on the hot path.** Lock acquisition runs in tight retry loops under contention. Keywords forwarded as `key:` shorthand and positional args into stateless `class << self` functions cost no extra objects; a parameter/context object, `**opts` hash, `Data`/`Struct` or builder allocates on every call (and per retry, per event). Fewer allocations = less GC pressure and more predictable latency in a concurrency primitive.
+- **The signature is the DSL.** `client.lock('name', ttl: 1_000, fail_fast: true, conflict_strategy: :work_through) { ... }` reads as a declarative per-call configuration. Users override exactly what they need; everything else falls back to `config[...]`. There is one place to look for what a call accepts.
+- **Layered defaults without merging.** Global config (`Config` DSL) → per-call keyword override → explicit forwarding. No hash merging, no hidden `opts.fetch`, no precedence rules to learn.
+- **Fail-fast on typos.** Ruby rejects unknown keywords (`ArgumentError: unknown keyword`) at the call boundary; an options hash would silently accept `tll:`.
+- **Typed and documented contract.** Every option has its own YARD `@option` line and RBS signature entry, so Steep and RBS runtime checks validate each value individually; opaque bags of options can't be typed this precisely.
+- **Stateless, thread/Ractor-friendly internals.** No intermediate object carries mutable state between layers; each function receives everything it needs as plain values, which keeps `Acquirer::*` modules pure and shareable.
+- **Grep-ability and traceability.** Searching for `log_sample_this:` shows every hop of a value from the public API down to the visitor that uses it.
+
+## How it is applied (layer by layer)
+| Layer | Style |
+|---|---|
+| `Client` public methods | Positional subject (`lock_name`) + long keyword list with defaults from `config['...']` or literals; trailing `&block`. Paired `x` / `x!` methods duplicate the full keyword list (no `**kwargs` delegation). |
+| `Client` → `Acquirer` | Explicit forwarding with Ruby 3.1 shorthand (`ttl:`, `queue_ttl:`); runtime identity values injected here (`process_id:`, `thread_id:`, `fiber_id:`, `ractor_id:`). |
+| `AcquireLock.acquire_lock` | Required keywords without defaults (`ttl:`, `timeout:`, ...): defaults live only in `Client`. |
+| Other `Acquirer::*`, mixins, visitors | Positional parameters in a fixed, documented order (subject, data, observability tail) for the cheapest possible internal calls. |
+| Results | Public API (`Client`, `Acquirer::*`, `Swarm` facade actions): small literal Hashes (`{ ok:, result: }`), not result classes. Internal swarm element APIs: bare scalars/primitives (see `swarm.md`). |
+
+## Claude rules
+1. **Do not introduce** parameter objects, context/options structs (`Data.define`, `Struct`, `OpenStruct`), builders, or `**opts` / `options = {}` hashes in `Client`, `Acquirer::*`, mixins or visitors. Long explicit lists are the intended design.
+2. New public option: add it as an explicit keyword to **every** affected `Client` method (`x` and `x!`, e.g. `lock` and `lock!`), with the default taken from `config['...']` (add the `setting` + `validate` first) or a literal for per-call-only flags (`raise_errors: false`, `meta: nil`).
+3. Forward it explicitly by name through every layer using shorthand (`new_option:`); never forward via `**kwargs`, `...`, or `method(__method__).parameters` tricks.
+4. Keep defaults only at the public boundary (`Client`); internal functions take required keywords/positionals with no defaults so a missed forward fails loudly.
+5. Internal positional lists: append new params in the established order (subject → domain data → observability tail `logger, instrumenter, instrument, log_sampling_*, log_sample_this, instr_sampling_*, instr_sample_this`) and update every call site and the RBS signature in the same change.
+6. Document each new option with its own `@option`/`@param` YARD line (type, meaning, default source) and add it to the RBS method signature as a named param/keyword.
+7. Keep hot-path code allocation-light: no per-call wrapper objects, no hash merging, no splats to build args, no `tap`/closures purely for argument plumbing; prefer passing existing locals.
+8. Silence length cops locally (`# rubocop:disable Metrics/MethodLength`) rather than shortening signatures; `Metrics/ParameterLists` is disabled project-wide on purpose.
+
+## Recommendations (proposed, not yet project policy)
+1. For new internal functions with many same-typed params (e.g. several Integers/Booleans in a row), consider required keywords instead of positionals to prevent misordering; keep the list flat and explicit.

data/.claude/rules/logic.md

@@ -0,0 +1,57 @@
+---
+paths:
+  - "lib/**/*.rb"
+---
+
+# Logic rules: general (`lib/`)
+
+Related rule files (loaded for narrower paths):
+- `acquirer.md`: acquirer operations, Redis access, `AcquireLock` algorithm
+- `visitors.md`: log & instrumentation visitors
+- `arguments.md`: long explicit keyword/parameter lists (core API design principle)
+- `swarm.md`: swarm architecture, element lifecycle, Ractor/Thread coding rules
+
+## Swarm overview (details in `swarm.md`)
+- Purpose: zombie-lock elimination. `ProbeHosts` periodically `HSET`s every host id (`rql:hst:<pid>/<thread>/<ractor>/<identity>`) with `Time.now.to_f` into `rql:swarm:hsts`; `FlushZombies` treats hosts older than `zombie_ttl` (ms) as zombies and deletes their locks, their queue entries and the hosts themselves.
+- `Client#swarm` → `Swarm` facade (one per client) owns a `Supervisor` and the swarm elements; started by `swarmize!` / `swarm.auto_swarm`, stopped by `deswarmize!`.
+- Elements are independent background units: a control unit (`SwarmElement::Threaded` = Thread + `SizedQueue` command channel; `SwarmElement::Isolated` = Ractor driven via its own pair of `Ractor::Port`s: results port created in the main Ractor, where the Swarm and Supervisor live; command port created inside the element Ractor) that spawns, stops and reports on a main-loop Thread with its own Redis connection (`Swarm::RedisClientBuilder`).
+- `ProbeHosts` is Threaded (it must see the client's ractor threads); `FlushZombies` is Isolated (copied config values only).
+- `Supervisor` is one Thread that calls `reswarm_if_dead!` on every element each `liveness_probing_period`, restarting dead control units or stopped main loops; `swarm_status` aggregates `{ running:, state: }` of all of them.
+- Redis work lives in stateless class-level functions (`ProbeHosts.probe_hosts`, `FlushZombies.flush_zombies`, `ZombieInfo.*`, `Acquirers.acquirers`), shared by main loops and the manual public API.
+
+## Observed conventions
+- Every file starts with `# frozen_string_literal: true`.
+- Constants are defined compactly: `class RedisQueuedLocks::Acquirer::IsLocked` / `module ...`, never nested `module A; module B`.
+- Namespace files (`acquirer.rb`, `swarm.rb`, `logging.rb`, `swarm/swarm_element.rb`) only `require_relative` their children; the root `lib/redis_queued_locks.rb` requires the namespaces in dependency order.
+- YARD doc block on every class, module, constant, attr and method:
+  `@param name [Type]`, `@option`, `@return [Type]`, blank `#` line, then `@api public|private`, `@since X.Y.Z`, optional `@version X.Y.Z` (latest behavior change).
+- Operations are stateless modules with `class << self` functions; dependencies (`redis_client`, logger, instrumenter, sampling options) are passed as explicit args, never read from globals.
+- Public API results are hashes `{ ok: Boolean, result: Symbol|Hash }` (`Client`, `Acquirer::*`, `Swarm` facade actions); `Client` `!` methods raise `RedisQueuedLocks::*Error`. Internal swarm element APIs return bare scalars/primitives (see `swarm.md`).
+- `Client` methods only fill defaults from `config['...']` and delegate to `Acquirer::*` / `Swarm`.
+- Redis keys come only from `RedisQueuedLocks::Resource.prepare_*` helpers and its `*_PATTERN` / `SWARM_KEY` constants.
+- Config: `setting('key', default)` + `validate('key') { |val| ... }` in `config.rb`; dotted keys for nested groups (`swarm.flush_zombies.zombie_ttl`); units in a trailing `# NOTE: in milliseconds` comment.
+- Errors: subclasses in `errors.rb`, written as `class XError < Error; end` (not `Class.new`) so RBS/Steep can see the superclass.
+- Comments use `# NOTE:`, `# TODO:` and `# @type var x: T` / `#: T` for inline type hints.
+- Rubocop is suppressed locally with `# rubocop:disable Metrics/MethodLength` etc. (paired `enable`), mostly for large algorithm methods.
+- Shared mutable state is guarded by `RedisQueuedLocks::Utilities::Lock#synchronize`; Ractor code must not capture non-shareable objects (build a fresh Redis client via `Swarm::RedisClientBuilder`).
+
+## Claude rules
+1. Start new files with `# frozen_string_literal: true` and use compact constant paths.
+2. Add a full YARD block to every new public/private method; new code gets `@since <next version>`; when changing existing behavior, add/bump `@version`.
+3. New operation = new `Acquirer::*` module + thin `Client` method delegating to it (+ `!` variant only if it must raise); details in `acquirer.md`.
+4. Return `{ ok:, result: }` hashes from public API operations (`Client`, `Acquirer::*`, `Swarm` facade actions); raise only in `!` methods or on invalid arguments (`RedisQueuedLocks::ArgumentError`). Internal APIs, and swarm element internals in particular, use bare scalars/primitives (`true`/`false`, String, Symbol, Integer, `nil`, a flat Hash of scalars) without the wrapper.
+5. Never hardcode `rql:` strings; add a `Resource.prepare_*` helper or constant instead.
+6. Use WATCH/MULTI or a Lua constant for any read-modify-write on lock/queue keys; never do check-then-set in Ruby without a transaction.
+7. New config option: `setting` with default + `validate` with a type check, both in `config.rb`; read it in `Client` as `config['key']`.
+8. Logs and instrumentation events go through visitor modules (see `visitors.md`); event names follow `redis_queued_locks.<snake_case>`.
+9. Keep thread/Ractor safety: guard shared state with `Utilities::Lock`, never share a `RedisClient` across Ractors.
+10. Disable rubocop cops only locally with a matching `rubocop:enable`, and only for Metrics/Layout on large methods.
+11. After any change here, update the mirrored `sig/` file (see `type-checking.md`) and add/adjust a spec (see `tests.md`).
+
+## Recommendations (proposed, not yet project policy)
+Apply to new or touched code; don't refactor existing code for these unless asked.
+1. Avoid `# rubocop:disable all` (used in `client.rb` lock_series and `lock_series_poc.rb`); disable only the specific cops.
+2. Document every option fully in YARD; `read_write_mode` is currently documented as `?` in `acquire_lock.rb`.
+3. Spell new identifiers correctly and don't copy existing typos (`swarm_element__termiante` method, `Acquier` in comments and the `acquier.rbs` filename); fix them only in a dedicated change.
+4. Include context in raised errors (lock name, acquirer id, timeout) so failures are diagnosable.
+5. Prefer `then` (the modern alias) over `yield_self` in new code.

data/.claude/rules/swarm.md

@@ -0,0 +1,119 @@
+---
+paths:
+  - "lib/redis_queued_locks/swarm.rb"
+  - "lib/redis_queued_locks/swarm/**/*.rb"
+  - "sig/redis_queued_locks/swarm.rbs"
+  - "sig/redis_queued_locks/swarm/**/*.rbs"
+---
+
+# Swarm rules (`lib/redis_queued_locks/swarm/**`)
+
+## Purpose
+The swarm removes **zombie locks**: locks and queue entries left by dead workers.
+- **Host**: a `process/thread/ractor/identity` worker, with the id `rql:hst:<pid>/<thread_id>/<ractor_id>/<identity>` (`Resource.host_identifier`). Fibers are not included because `ObjectSpace` can't see Fibers or Threads once a Ractor exists. Hosts are enumerated with `Thread.list` (`Resource.possible_host_identifiers`).
+- **Liveness**: `ProbeHosts` runs `HSET rql:swarm:hsts <host_id> <Time.now.to_f>` for every possible host of the client's ractor (`Resource::SWARM_KEY`).
+- **Zombie**: a host whose last probe score is `< Resource.calc_zombie_score(zombie_ttl / 1_000.0)` (`now - ttl`). `zombie_ttl` is in milliseconds. Zombie locks are `rql:lock:*` whose `hst_id` field is a zombie host. Zombie acquirers are their `acq_id`s.
+- **Flush** (`FlushZombies.flush_zombies`) runs these steps: `HGETALL` hosts → zombie hosts (return early if none) → `SCAN MATCH rql:lock:*` + `HMGET acq_id hst_id` → `DEL` zombie locks → `SCAN MATCH rql:lock_queue:*` + `ZREM` zombie acquirers → `HDEL` zombie hosts. It is best-effort and non-transactional, with full keyspace scans (`TODO: indexing`).
+
+## Components
+| Object | File | Kind | Role |
+|---|---|---|---|
+| `Swarm` | `swarm.rb` | facade (one per `Client`, `client.swarm`) | owns the supervisor and elements. Public API: `swarm!`/`deswarm!`, `swarm_status`, `swarm_info`, `probe_hosts`, `flush_zombies`, `zombie_*`/`zombies_info`. Guards everything with its own `sync` |
+| `Swarm::Supervisor` | `swarm/supervisor.rb` | plain `Thread` (`visor`) | every `swarm.supervisor.liveness_probing_period` seconds it runs the `observable` block, which calls `reswarm_if_dead!` on every element |
+| `SwarmElement::Threaded` | `swarm/swarm_element/threaded.rb` | abstract base | control `Thread` plus a main-loop `Thread` |
+| `SwarmElement::Isolated` | `swarm/swarm_element/isolated.rb` | abstract base | control `Ractor` plus a main-loop `Thread` inside it, driven through a per-element pair of `Ractor::Port`s |
+| `ProbeHosts` | `swarm/probe_hosts.rb` | `< Threaded` | periodic host liveness probes |
+| `FlushZombies` | `swarm/flush_zombies.rb` | `< Isolated` | periodic zombie flushing |
+| `Acquirers`, `ZombieInfo` | `swarm/acquirers.rb`, `swarm/zombie_info.rb` | stateless `class << self` modules | read-only queries (`HGETALL` swarm hash, lock `SCAN`s) |
+| `RedisClientBuilder` | `swarm/redis_client_builder.rb` | stateless module | `build(pooled:, sentinel:, config:, pool_config:)` returns a fresh `RedisClient` or `RedisClient::Pooled` |
+
+`Client` methods `swarmize!`, `deswarmize!`, `swarm_status`/`swarm_state`, `swarm_info`, `probe_hosts`, `flush_zombies`, `zombie_locks`, `zombie_acquirers`, `zombie_hosts`, `zombies_info`/`zombies` only fill defaults from `config['swarm.*']` and delegate to `Swarm`. `Client#initialize` calls `swarm.swarm!` when `swarm.auto_swarm` is set.
+
+## Why Threaded vs Isolated
+- `ProbeHosts` **must** be Threaded. Host ids come from `Thread.list` and `Ractor.current` of the client's ractor, so a probe from another Ractor would announce the wrong hosts. It may read `rql_client` (same ractor).
+- `FlushZombies` is Isolated. The heavy `SCAN`/`DEL` work runs in its own Ractor with its own Redis connection, isolated from the app's ractor and objects. Everything it needs is passed into `Ractor.new(...)` as copied plain values (`config.slice('swarm.flush_zombies.redis_config')`, which `dup`s values, plus Integers). It never touches `rql_client` inside the ractor.
+
+## Element lifecycle (both bases)
+Each element has two layers, with different code for each base:
+1. **Control unit** (`swarm_element`). Threaded: a `Thread` reading `swarm_element_commands` (`Thread::SizedQueue.new(1)`) and replying on `swarm_element_results` (`SizedQueue(1)`). Isolated: a `Ractor` running `self.swarm_loop(swarm_element_results_port)` that reads `swarm_element_commands_port` and replies on `swarm_element_results_port`, both `Ractor::Port`s (see "Isolated ports" below).
+2. **Main loop**: a `Thread` that does the actual periodic work (`loop { op(redis_client, ...); sleep(period) }`), with a Redis client built inside the thread by `RedisClientBuilder` from `swarm.<element>.redis_config.*`.
+
+Phases: **init** `swarm!` (create control unit, loop not started) → **start** `swarm_loop__start` (kill old main loop, spawn new) → **stop** `swarm_loop__stop` kills only the main loop → **kill** `swarm_element__termiante` (Threaded: kill both threads, close and clear queues, nil them) / `swarm_loop__kill` (Isolated: `:kill` makes the ractor kill and join all its threads, ack, and leave its loop; the host then `join`s the ractor).
+
+Command protocol: the same bare-value replies in both bases (see "Internal API: scalars and primitives" below).
+| Command | Reply |
+|---|---|
+| `:status` | `{ alive: Boolean, state: String }` |
+| `:is_active` | `true` / `false` |
+| `:start` / `:stop` | `true` (ack) |
+| `:kill` | Isolated only: `true` (ack), then the ractor finishes. Threaded is terminated from outside. |
+
+Every request/reply pair is wrapped in `sync.synchronize` so concurrent callers can't interleave on the channel, and each reply belongs to the command just sent. Both bases send every command through one helper, `swarm_loop__send_command(command)`, which returns the reply, or `nil` when the element is dead (or, in Threaded, terminating). Abstract hooks (`spawn_main_loop!`, `spawn_swarm_element!`) raise `NotImplementedError` in the bases.
+
+## Internal API: scalars and primitives
+`{ ok:, result: }` is the **public API** contract only: `Client` methods, `Acquirer::*` operations, and the `Swarm` facade's public methods (`swarm!`/`deswarm!`, plus the stateless operations behind `client.probe_hosts` / `client.flush_zombies`). Status reports (`swarm_status`, element `#status`, `Supervisor#status`) are plain nested Hashes with no wrapper.
+
+Everything inside swarm elements is internal API and uses bare scalars and primitives, with no `{ ok:, result: }` wrapper. That covers control-unit commands and replies, the Isolated handshake, port and queue messages, `swarm_loop__*` helpers, `swarmed__*` predicates and main-loop plumbing.
+- **Commands**: Symbols (`:status`, `:is_active`, `:start`, `:stop`, `:kill`).
+- **Replies**: the value itself. Use `true`/`false` for questions and `true` as the ack for actions. Use a String/Symbol/Integer/Float for a single datum, and a flat Hash of scalars (`{ alive:, state: }`) only when a reply carries several related values. Don't nest.
+- **Handshake**: the commands port itself, sent as the first message.
+- **"No answer" / dead element**: `nil`. On the results port, a Symbol (`:exited`/`:aborted`) is reserved for the `Ractor#monitor` death notice, so never reply with a Symbol there. If a datum is a Symbol, send it as a String.
+- **Errors**: don't wrap them in replies. A failing main loop just dies, and a dead control unit is detected through liveness, the monitor notice or `nil`.
+
+## Isolated ports (`Ractor::Port`)
+Only the Ractor that created a port can `receive` from it; any Ractor can send to it. So each Isolated element owns two ports:
+- **`swarm_element_results_port`**: created in the **main Ractor** by `swarm!`. The Swarm and its Supervisor live there, and so do all callers of the element API. It receives command replies and also the Ractor's termination notice: `swarm!` calls `swarm_element.monitor(results)`, which sends `:exited`/`:aborted`, immediately if the Ractor has already finished.
+- **`swarm_element_commands_port`**: created **inside the element Ractor** by `.swarm_loop`. It's handed to the main Ractor as the first message on the results port (the handshake: the port itself; any other first message means the Ractor died during startup), which `swarm!` waits for.
+
+Ports belong to the element instance, so any number of Isolated elements work side by side without sharing channels. A new `swarm!` creates a fresh pair, and stale messages left in an old results port are dropped with it.
+
+Failure handling in `swarm_loop__send_command`:
+- A non-Hash reply (`:exited`/`:aborted`) means the Ractor died, so the request returns `nil`.
+- Sending to a finished Ractor's port raises `Ractor::ClosedError`, which is also rescued to `nil`.
+- No request can block forever, because the monitor notice always arrives.
+
+Thread hygiene inside the Ractor: a Ractor stays `running` until **all** its threads have finished. Killed but un-joined threads count, and so do helper threads that `Socket.tcp` leaves behind when the loop is killed mid-connect. `.terminate_thread` therefore kills and joins. `:kill` terminates every thread of the Ractor (`Thread.list - [Thread.current]`) before acking, and `swarm_loop__kill` joins the Ractor, so the status is `terminated` as soon as `try_kill!` returns.
+
+State predicates (private, same names in both bases): `idle?` (no control unit), `swarmed?`, `swarmed__alive?`, `swarmed__dead?`, `swarmed__running?` (alive and main loop active), `swarmed__stopped?` (alive, loop inactive). Threaded also has `terminating?` (queues nil/closed). In Isolated, `swarmed__running?`/`swarmed__stopped?` return `false` when the request returned `nil` (the element died mid-request). Liveness: Threaded uses `Thread#alive?`; Isolated uses `Utilities.ractor_alive?`/`ractor_status`, which parse `Ractor#to_s` because Ractor has no status API. Thread state uses `Utilities.thread_state` (`'dead'`/`'failed'`/`Thread#status`).
+
+Public element API (called by `Swarm`/`Supervisor` only):
+- `try_swarm!`: no-op unless `enabled?`; terminate, then `swarm!`, then start.
+- `reswarm_if_dead!`: no-op unless `enabled?`; `swarmed__stopped?` → restart the loop; `swarmed__dead? || idle?` → `swarm!` and start. This is how a crashed main loop (`abort_on_exception = false`) or a killed element recovers.
+- `try_kill!`: terminate regardless of `enabled?`.
+- `status`: Threaded `{ enabled:, thread: { running:, state: }, main_loop: { running:, state: } }`; Isolated is the same with `ractor:` instead of `thread:`. Unborn parts report `'non_initialized'`. Isolated gets the main loop part from a single `:status` request, and a dead element reports `'non_initialized'`.
+
+## Swarm orchestration (`Swarm#swarm!` / `#deswarm!`)
+- `swarm!` (under `sync`): `supervisor.stop!` → each `element.try_swarm!` → `supervisor.observe! { each element.reswarm_if_dead! }` unless running → `sleep(0.1)` → `{ ok: true, result: :swarming }`. It can be called again; it re-creates everything.
+- `deswarm!`: `supervisor.stop!` first, so it doesn't resurrect elements, then each `element.try_kill!` → `sleep(0.1)` → `{ ok: true, result: :terminating }`.
+- `swarm_status`: `{ auto_swarm:, supervisor: { running:, state:, observable: }, probe_hosts: <status>, flush_zombies: <status> }`.
+- The supervisor block swallows errors (`yield rescue nil`), so a failing element never kills the visor.
+
+## Config (`config.rb`)
+`swarm.auto_swarm`, `swarm.supervisor.liveness_probing_period` (s). Per element: `swarm.<el>.enabled_for_swarm`, a period (`probe_hosts.probe_period` s, `flush_zombies.zombie_flush_period` s), and the 4-key `swarm.<el>.redis_config.{sentinel,pooled,config,pool_config}` group. Flush extras: `zombie_ttl` (ms), `zombie_lock_scan_size`, `zombie_queue_scan_size`.
+
+## Claude rules
+1. Swarm operations are stateless class-level functions (`ProbeHosts.probe_hosts`, `FlushZombies.flush_zombies`, `ZombieInfo.*`, `Acquirers.acquirers`) that take `redis_client` plus plain values. The manual public API and the main loop call the same function. Don't put Redis logic in instance methods.
+2. New element: subclass `Threaded` (it needs the client's ractor: threads, `rql_client`, or non-shareable objects) or `Isolated` (self-contained work on copied values). Implement `enabled?` plus `spawn_main_loop!` (Threaded, returns the `Thread`) or `spawn_swarm_element!(swarm_element_results_port)` (Isolated: return `Ractor.new(swarm_element_results_port, <plain args>) { |r_res_p, ...| <Klass>.swarm_loop(r_res_p) { Thread.new { ... } } }`). Don't override `swarm!` in Isolated subclasses; the base wires the ports, the monitor and the handshake.
+3. Register a new element everywhere: `attr_reader` + `initialize`, `swarm!` (`try_swarm!`), the supervisor block (`reswarm_if_dead!`), `deswarm!` (`try_kill!`), `swarm_status`. Add the config group (`enabled_for_swarm`, period, `redis_config.*`) with `validate`s, and add `Client` delegators with config defaults.
+4. Main loops build their own Redis client with `RedisClientBuilder` inside the loop thread. Never reuse `rql_client.redis_client` in a loop, and never pass a client, logger or other non-shareable object into a Ractor. Pass `config.slice(...)` and scalars instead.
+5. Inside a Ractor, reference only shareable constants and module functions (`RedisQueuedLocks::Swarm::X.op`, `RedisQueuedLocks::Resource`, `RedisQueuedLocks::Utilities`). No instance state, no captured locals.
+6. Change element state only inside `sync.synchronize`. `Utilities::Lock` is a reentrant `Monitor`, so the public→private nesting is intended. Keep the single-slot request/reply pairing atomic.
+7. Keep the lifecycle API names and semantics (`try_swarm!`, `reswarm_if_dead!`, `try_kill!`, `status`, the `swarmed__*` predicates, the `:status`/`:is_active`/`:start`/`:stop`/`:kill` commands) the same across both bases. The supervisor and `Swarm` rely on that duck typing.
+8. Main loop threads must have `abort_on_exception = false` (both control units set this) and let errors kill only the loop. Recovery belongs to the supervisor, so don't add retry loops inside elements.
+9. Stop the supervisor before killing or re-creating elements, or it will race and resurrect them.
+10. Report element status as the nested `{ running:, state: }` hashes with `'non_initialized'` for missing parts. Update `swarm_status` RBS types when the shape changes.
+11. Zombie detection compares probe scores (`Time.now.to_f`) with `Resource.calc_zombie_score`. Keep `zombie_ttl` in ms at the API and convert with `/ 1_000.0`. Use `Resource::SWARM_KEY`/`*_PATTERN` and never hardcode keys.
+12. Mirror every change in `sig/redis_queued_locks/swarm/**` and keep the existing `# steep:ignore` on nil-narrowed `Thread?`/`Ractor?` calls (Steep doesn't narrow `attr_reader` results).
+13. Isolated communication goes only through `Ractor::Port`s: create the results port in the main Ractor (`swarm!`) and the command port inside the element Ractor (`.swarm_loop`), and register `Ractor#monitor` on the results port before waiting on it. Every command gets exactly one reply, sent before the Ractor leaves its loop. Treat Symbol replies as death notices. Don't use `Ractor.receive`, `Ractor#send` or the default port, and never share one port between elements. Naming: port variables, attributes and params end in `_port` (`swarm_element_results_port`, `swarm_element_commands_port`). Block (proc) params use short initial-letter names (`r_res_p` for the results port, `r_com_p` for the commands port), like the other abbreviated Ractor block params (`rc`, `z_ttl`).
+14. Inside an element Ractor, terminate threads with kill + join (`.terminate_thread`) and keep `:kill` terminating every thread of the Ractor. Otherwise its status lags as `running`.
+15. Don't use `{ ok:, result: }` inside swarm elements (see "Internal API: scalars and primitives"). Commands are Symbols. Replies, helper returns and predicates are bare scalars/primitives, or a flat Hash of scalars, with `nil` for "no answer / dead". Keep the wrapper only at the public boundary (`Client`, `Acquirer::*`, `Swarm#swarm!`/`#deswarm!`, `ProbeHosts.probe_hosts`, `FlushZombies.flush_zombies`). Type internal replies in RBS as literal types/unions (`bool`, `String`, `{ alive: bool, state: String }`) rather than `xxxResult` records.
+16. Swarm specs (in `describe 'swarm'`) deal with real timing: set short periods via config, kill elements with `try_kill!`, wait longer than `liveness_probing_period`, and match states loosely (`eq('running').or(eq('blocking'))`, `'sleep'`/`'run'`).
+
+## Known quirks (don't copy; fix only in a dedicated change)
+- Typos: `swarm_element__termiante`, `@since 19.0.0` on `Threaded#reswarm_if_dead!`, `@api ppublic` on `Swarm#zombie_acquirers`, "lopp"/"teh" in comments.
+- `swarm_loop__stop` is not used by the swarm itself, only by specs.
+- Killing an element while its main loop is still connecting to Redis makes Ruby's `Socket.tcp` helper threads print `terminated with exception ... IO#write` reports. This is harmless noise from the stdlib.
+- `sleep(0.1)` "give a timespot" waits in `swarm!`/`deswarm!`/`observe!` instead of real readiness signalling.
+- RBS runtime type checking (`rbs/test/setup`, the `typecheck-runtime` CI job) can't run inside Ractors. Its hooks on methods called in the element Ractor (`.swarm_loop`, `.flush_zombies`) read `RBS.logger` and raise `Ractor::IsolationError`, so Isolated elements die at startup and the swarm specs fail only under that job.
+- Swarm has no logging or instrumentation, and supervisor errors are silently dropped (`TODO: (CHECK)`).
+- `FlushZombies` scans the whole keyspace on every run and runs `ZREM` for every zombie acquirer on every queue.

data/.claude/rules/tests.md

@@ -0,0 +1,42 @@
+---
+paths:
+  - "spec/**/*.rb"
+  - ".rspec"
+---
+
+# Test rules (`spec/`)
+
+## Observed conventions
+- All behavior specs live in one integration file, `spec/redis_queued_locks_spec.rb`, under `RSpec.describe RedisQueuedLocks`. The file header says it will be reworked; rspec-retry (5 retries) masks flakiness meanwhile.
+- `.rspec` auto-requires `spec_helper`; `spec_helper.rb` loads SimpleCov first (`setup_simplecov.rb`), then `rspec/retry`, `pry`, the gem.
+- RSpec config: random order (`Kernel.srand config.seed`), `disable_monkey_patching!`, `expect` syntax only, `filter_run_when_matching :focus`, `Thread.abort_on_exception = true`.
+- Tests hit a real Redis (db 0) via `let(:redis) { RedisClient.config(db: 0).new_pool(timeout: 5, size: 50, ...) }` with long timeouts (RBS runtime-check runs are slow).
+- `before`: `FLUSHDB`, `DEL Resource::SWARM_KEY`, `RedisQueuedLocks.enable_debugger!`; `after`: `DEL SWARM_KEY`, `FLUSHDB`.
+- Examples are written with `specify '<feature>'` (few `it`); grouped with `describe` only for big areas (`'Lock Series PoC'`, `'swarm'`).
+- Clients are built inline: `RedisQueuedLocks::Client.new(redis) { |config| ... }`.
+- Logger/instrumenter fakes are anonymous classes (`Class.new { def debug(...); def notify(event, payload = {}) }`) collecting calls into arrays.
+- Concurrency is tested with real `Thread.new` and `sleep` to wait for async swarm elements; assertions use `match(...)`, `eq(...).or(eq(...))`, `include`, `raise_error(RedisQueuedLocks::...Error)`.
+- Every example cleans up its own state (`client.clear_locks`, `deswarmize!`, `redis.close`).
+- Coverage: SimpleCov line + branch, HTML only; `minimum_coverage 100` is a TODO.
+
+## Claude rules
+1. Run specs with a local Redis available: `bundle exec rake rspec` (single example: `bundle exec rspec spec/redis_queued_locks_spec.rb:<line>`).
+2. Add new examples to `spec/redis_queued_locks_spec.rb` with `specify '<feature>'`, inside an existing `describe` when one fits; don't create new spec files unless asked (the suite is pending a rework).
+3. Use only `expect` syntax; no `should`, no monkey-patched DSL, no `focus` left behind.
+4. Use the shared `redis` pool and rely on the global `before`/`after` FLUSHDB; never use a different DB or flush in the middle of an example without reason.
+5. Build fakes as anonymous classes implementing the duck-typed interface (`debug`, `notify`, `sampling_happened?`), not with doubles of real loggers.
+6. Clean up everything an example starts: release locks, `deswarmize!` swarm clients, join/kill threads.
+7. Keep `sleep`-based waits minimal and comment why (`# give a timespot to ...`); prefer polling with a bounded timeout when adding new async checks.
+8. Do not add new rspec-retry reliance or lower retry settings; do not enable `minimum_coverage` without being asked.
+9. Specs are also run under RBS runtime checks, so pass correctly typed arguments to public API calls (type violations are logged in CI).
+
+## Recommendations (proposed, not yet project policy)
+Apply to new tests; don't restructure the existing suite unless asked.
+1. Move toward one spec file per feature, mirroring `lib/` (`spec/redis_queued_locks/acquirer/extend_lock_ttl_spec.rb`), when the planned rework starts.
+2. Extract the repeated fake logger/notifier classes into `spec/support/` shared helpers or `shared_context`.
+3. Add a `wait_until(timeout:) { condition }` helper and use it instead of fixed `sleep` for swarm/thread checks; this reduces flakiness and rspec-retry reliance.
+4. Add Redis-free unit specs for pure modules (`Resource`, `Config` + validators, samplers, `Logging.should_log?`); they are fast and stable.
+5. Tag slow swarm/Ractor examples (e.g. `:swarm`) so they can be run or skipped separately.
+6. Read the Redis connection from `ENV['REDIS_URL']` (default `redis://localhost:6379/0`) so specs can run against non-default Redis setups.
+7. Once the suite is stable, remove rspec-retry and raise `minimum_coverage` step by step toward 100.
+8. Cover failure paths explicitly: timeouts, retry exhaustion, `fail_fast`, `raise_errors`, each conflict and access strategy.