redis_queued_locks 1.22.0 → 1.23.1

data/.claude/rules/visitors.md

@@ -22,7 +22,10 @@ The project calls these modules "visitors", but they are not GoF Visitor (no `ac
 | `AcquireLock::TryToLock::LogVisitor` | `acquire_lock/try_to_lock/log_visitor.rb` | 19 step-level events (`start`, `rconn_fetched`, `acq_added_to_queue`, `dead_request_removed`, `exit__no_first`, `exit__read_lock_still_obtained`, `obtain__free_to_acquire`, ...); every lock event logs `rw_mode` |
 | `AcquireLock::YieldExpire::LogVisitor` | `acquire_lock/yield_expire/log_visitor.rb` | `expire_lock`, `decrease_lock` |
 | `AcquireLock::DequeueFromLockQueue::LogVisitor` | `acquire_lock/dequeue_from_lock_queue/log_visitor.rb` | `dequeue_from_lock_queue` |
-| `LockSeriesPoC::LogVisitor` / `InstrVisitor` | `lock_series_poc/*_visitor.rb` | lock series events (no RBS, `# steep:ignore`): `start_lock_series_obtaining`, `lock_series_obtained`, `expire_lock_series` / `lock_series_obtained`, `lock_series_hold_and_release`; all of them log/carry `rw_mode` (the mode of the series) |
+| `LockSeries::LogVisitor` | `lock_series/log_visitor.rb` | 11: `start_lock_series_obtaining`, `start_try_to_lock_series_cycle`, `dead_score_reached__reset_series_position`, `lock_series_intermediate_lock_obtained`, `lock_series_lock_obtained`, `lock_series_lock_obtaining_failed`, `lock_series_obtained`, `lock_series_obtaining_failed`, `dequeue_from_lock_series_queues`, `expire_lock_series`, `decrease_lock_series`; `rw_mode` (the mode of the series) and `priority` in all of them |
+| `LockSeries::InstrVisitor` | `lock_series/instr_visitor.rb` | 6: `lock_series_intermediate_lock_obtained`, `lock_series_lock_obtained`, `lock_series_lock_obtaining_failed`, `lock_series_obtained`, `lock_series_hold_and_release`, `lock_series_obtaining_failed`; `rw_mode` and `priority` in all of them |
+
+`TryToLockSeries` writes the try-lock logs of each lock through `TryToLock::LogVisitor` (the `LogVisitor` constant there: `TryToLock` is included; the per-lock loops are gated by `log_sampled && log_lock_try`): no own try-lock events.
 
 Not covered by visitors (lock mutation operations, `logic.md#16`): `ReleaseLock`, `ReleaseReadLock`, `ReleaseAllLocks`, `ReleaseLocksOf`, `ExtendLockTTL`, `ClearDeadRequests`, `ReindexLocks` write one log line (`logger.debug`) and one event (`instrumenter.notify`) inline inside `run_non_critical` after the whole operation: `explicit_lock_release`, `explicit_read_lock_release`, `explicit_all_locks_release`, `release_locks_of`, `extend_lock_ttl`, `clear_dead_requests`, `reindex_locks` (the log line has the event name and the payload data in the same order, without `instrument`; the payload ends with `instrument`). `lock_obtaining_failed` is reported by `acquire_lock` in Step 3.b (the failure result) and in the method-level `rescue` of the raised acquirement errors (Step 3.c: only while the lock is not acquired; errors of the block of code are not reported).
 
@@ -31,20 +34,20 @@ Not covered by visitors (lock mutation operations, `logic.md#16`): `ReleaseLock`
 - **Shape**: `module <Component>::LogVisitor` / `::InstrVisitor`, `# @api private`, all methods inside `class << self`, full YARD block per method; return `void`.
 - **Method name = event name**: snake_case; double underscore separates phase and detail (`exit__queue_ttl_reached`, `reentrant_lock__work_through`). The LogVisitor and InstrVisitor use the same method name for the same event.
 - **Parameter order**: `(port, sampled_flag, [extra gate], lock_key, ...event data..., [instrument])`:
-  - LogVisitor: `(logger, log_sampled, ...)`; `TryToLock::LogVisitor` adds `log_lock_try` as the third arg (fine-grained step logs are opt-in through `config['log_lock_try']`). Lock lifecycle events (AcquireLock, TryToLock, YieldExpire, DequeueFromLockQueue, LockSeriesPoC) take `rw_mode` right after `access_strategy`, before event-specific data, and log it as `rw_mode => '<mode>'` right after `acs_strat`; the lock acquirement logs of `AcquireLock::LogVisitor` (all of them), `LockSeriesPoC::LogVisitor` (the priority of the series) and `TryToLock::LogVisitor.acq_added_to_queue` take `priority` right after `rw_mode` and log `priority => N` right after it (the release logs of `YieldExpire` and `DequeueFromLockQueue` don't); try-lock logs that name another request log its decoded priority right after its acquirer (`first_priority_in_queue` after `first_acq_id_in_queue`, `ahead_priority` after `ahead_acq_id`, `dead_priority` after `dead_acq_id`; `Integer?` params decoded at the call site only when `log_sampled && log_lock_try`, by one helper: `TryToLock#logged_request_priority`, see rule 12).
+  - LogVisitor: `(logger, log_sampled, ...)`; `TryToLock::LogVisitor` adds `log_lock_try` as the third arg (fine-grained step logs are opt-in through `config['log_lock_try']`). Lock lifecycle events (AcquireLock, TryToLock, YieldExpire, DequeueFromLockQueue, LockSeries) take `rw_mode` right after `access_strategy`, before event-specific data, and log it as `rw_mode => '<mode>'` right after `acs_strat`; the lock acquirement logs of `AcquireLock::LogVisitor` (all of them), `LockSeries::LogVisitor` (the priority of the series) and `TryToLock::LogVisitor.acq_added_to_queue` take `priority` right after `rw_mode` and log `priority => N` right after it (the release logs of `YieldExpire` and `DequeueFromLockQueue` don't); try-lock logs that name another request log its decoded priority right after its acquirer (`first_priority_in_queue` after `first_acq_id_in_queue`, `ahead_priority` after `ahead_acq_id`, `dead_priority` after `dead_acq_id`; `Integer?` params decoded at the call site only when `log_sampled && log_lock_try`, by one helper: `TryToLock#logged_request_priority`, see rule 12).
   - InstrVisitor: `(instrumenter, instr_sampled, lock_key, rw_mode, ttl, acq_id, hst_id, ts, acq_time, [hold_time], instrument)`; the payload carries `rw_mode:` (requested mode); the user's `instrument` value is always last. All lock acquirement events (`lock_obtained`, `lock_hold_and_release`, `lock_obtaining_failed`, the reentrant ones: the requested priority, they never queue; the lock series ones: the priority of the series) take `priority` (the lock request priority: always the Integer, a priority name is resolved before) right after `rw_mode` (payload `priority:` after `rw_mode:`).
-  - `rw_mode` in AcquireLock/TryToLock/DequeueFromLockQueue events is the **requested** mode; in YieldExpire events it is the **held** mode (the lock that is released/decreased); in LockSeriesPoC events it is the mode of the series (`read_write_mode`, one for all locks of the series). LockSeriesPoC instrumentation takes `rw_mode` right after `lock_keys`.
+  - `rw_mode` in AcquireLock/TryToLock/DequeueFromLockQueue events is the **requested** mode; in YieldExpire events it is the **held** mode (the lock that is released/decreased); in LockSeries events it is the mode of the series (one for all locks of the series). LockSeries instrumentation takes `rw_mode` right after `lock_keys`: the series events have `lock_keys` instead of `lock_key`, the events of a lock of the series (`lock_series_*lock_*`) have both (`lock_key, lock_keys`). The per-lock series events are not per-attempt events (`logic.md#16`): `lock_series_intermediate_lock_obtained` is reported once per lock by `lock_series`, out of the WATCH block of the attempt.
 - **Guard first**: `return unless log_sampled` (`&& log_lock_try` for try-lock steps) / `return unless instr_sampled`. The sampling decision is computed **once per operation** in the caller via `Logging.should_log?` / `Instrument.should_instrument?` and passed down as a boolean.
 - **Log format**: one `logger.debug { ... }` block (lazy string), message = `"[redis_queued_locks.<event>] "` (`[redis_queued_locks.try_lock.<event>]` for TryToLock steps) followed by `key => value` pairs; string values in single quotes (`lock_key => '...'`), numbers bare (a missing number of an `Integer?` param is logged as `nil` with `#inspect`, never as an empty value: `first_priority_in_queue => nil`); abbreviated keys `acq_id`, `hst_id`, `acs_strat`. Built with `\` line continuations.
 - **Instrumentation format**: `instrumenter.notify('redis_queued_locks.<event>', { lock_key:, ttl:, acq_id:, hst_id:, ts:, acq_time:, instrument: })` using shorthand hash syntax and Symbol keys.
 - **Never raise**: every emit ends with `rescue nil` (modifier), so a broken logger/instrumenter can't affect lock correctness.
 - **Call sites**: plain module calls with positional args, usually grouped on 2-3 lines (`LogVisitor.lock_obtained(logger, log_sampled, lock_key, ...)`); data comes from local vars or the `result` hash of the step.
-- **Typing**: each visitor (except lock_series_poc) has an RBS file with `def self.<event>: (RQL::loggerObj logger, bool log_sampled, ...) -> void` / `RQL::instrObj instrumenter`.
+- **Typing**: each visitor has an RBS file with `def self.<event>: (RQL::loggerObj logger, bool log_sampled, ...) -> void` / `RQL::instrObj instrumenter`.
 - **User docs**: README documents every log event with its logged keys (`## Logging`: the default, `log_lock_try`, lock series and operation logs lists, mirrored in the `config['logger']` / `config['log_lock_try']` comments of `### Logging Configuration` and `### Configuration`) and every instrumentation event with its payload keys, types and semantics (`### Instrumentation Events`).
 
 ## Claude rules
 **When to use**
-1. Any new log line or instrumentation event inside `AcquireLock` (and its mixins) or `LockSeriesPoC` must go through a visitor method; never call `logger.*` or `instrumenter.notify` directly in algorithm code.
+1. Any new log line or instrumentation event inside `AcquireLock`, `LockSeries` (and their mixins) must go through a visitor method; never call `logger.*` or `instrumenter.notify` directly in algorithm code.
 2. Add a LogVisitor event for each new meaningful step or branch of the algorithm (start, decision, exit, success). Add an InstrVisitor event for the outcomes users would want to measure (obtained, not obtained, held/released, completed); not for internal per-attempt steps (`logic.md#16`).
 3. Fine-grained per-attempt logging belongs in `TryToLock::LogVisitor` and must be gated by `log_lock_try`.
 4. For a new algorithm component (new mixin under `acquire_lock/`), create its own `<component>/log_visitor.rb` (and `instr_visitor.rb` if needed) and `require_relative` it from the component.
@@ -65,4 +68,3 @@ Not covered by visitors (lock mutation operations, `logic.md#16`): `ReleaseLock`
 Apply to new or touched code; don't refactor existing code for these unless asked.
 1. Use one error-swallowing style consistently (visitors use modifier `rescue nil`, mutation modules use `run_non_critical`). Both silently hide bugs such as a `NoMethodError` inside the log block, so consider reporting swallowed errors when the debugger is enabled.
 2. Keep log and instrumentation event names in one registry constant (e.g. `RedisQueuedLocks::Instrument::EVENTS`) so README, specs and RBS can be checked against it.
-3. Add RBS for the `lock_series_poc` visitors when the PoC stabilizes.

data/.claude/skills/rql-code-review/SKILL.md

@@ -82,16 +82,18 @@ priorities", key layout, "Lock index", lock lookup modes, events, errors, conven
   - `EXTEND_LOCK_PTTL` in `TryToLock` and `ExtendLockTTL`;
   - lock state reply reading in `try_to_lock` Step 0.1 and `precheck_lock` (shared `pipeline_lock_state`,
     position constants, `lock_obstacle`, `log_lock_obstacle`);
-  - reserved `meta` keys validation in `AcquireLock` and `LockSeriesPoC`; the `priority` resolution and range check
-    in `AcquireLock` Step 0.1 and `LockSeriesPoC` (the same message);
+  - the argument validations of `AcquireLock` Step 0 and `LockSeries` Step 0 (reserved `meta` keys, numeric ranges, the
+    `priority` resolution and range check: the same messages);
+  - the attempt flow of `TryToLock#try_to_lock`/`precheck_lock` and `TryToLockSeries#try_to_lock_series`/`precheck_lock_series`
+    (the commands and decisions are shared helpers, the flow exists twice), `drop_dead_requests_ahead` and
+    `drop_series_dead_requests_ahead`;
   - the band liveness rule (a request is dead when its score is `<= Resource.lock_priority_band_dead_score(dead_score,
     band)`): `TryToLock#dead_request_priority` / `pipeline_dead_requests_removal` and `ClearDeadRequests.drop_dead_requests` /
     `drop_dead_requests_by_priority`;
   - the `'priority'` field of a request (`Resource.lock_request_priority`) in `QueueInfo.queue_info` and
     `Queues.extract_queues_info`;
-  - lock-family options in `Client#lock`, `#lock!`, `#lock_series`, `#lock_series!` and their forwarding in
-    `LockSeriesPoC.lock_series_poc`.
-- Mirror path exception: `lock_series_poc*` has no RBS.
+  - lock-family options in `Client#lock`, `#lock!`, `#lock_series`, `#lock_series!` and the keyword lists of
+    `AcquireLock.acquire_lock` and `LockSeries.lock_series`.
 - Next version for `@since`/`@version`: the version the unreleased work already uses (`git diff <base> -- lib |
   grep -oE '^\+.*@(since|version) [0-9.]+'`, the CHANGELOG `[Unreleased]` code), otherwise the next minor of
   `RedisQueuedLocks::VERSION` (`version.rb`); don't take the maximum over `lib/` (old tags can be wrong).
@@ -169,12 +171,14 @@ Still in scope (the exemption covers how specs are written, not whether the libr
   `yield_expire` (a read request that works through the own write lock holds the write lock); a reader is released
   owner-safe (`ZREM` of the own member + `DEL` of the own reader data), `unlock` releases everything; the internal
   `rw_mode` never appears in the public `lock` result.
-- Read lock extension (`extend_lock_ttl(..., read_write_mode: :read)`): `multi(watch: [lock_key])`, only a live read
+- Read lock extension (`extend_lock_ttl(..., rw_mode: :read)`): `multi(watch: [lock_key])`, only a live read
   lock and only while no write lock exists, never revives an expired reader; `all_read_locks: true` extends every
   live reader (`ZADD XX INCR`), the registry/reader data TTLs keep the max (`PEXPIRE NX` + `GT`).
 - `fail_fast`: write fails on a write holder or live readers, read fails on a write holder (or the own live read);
-  lock series: one mode for the whole series, `release_lock_series` releases only the locks the series obtained and
-  only the current acquirer's (write: compare-and-delete in one transaction, read: `ZREM` + `DEL`).
+  lock series: one mode for the whole series, one `acquirer_position` in all its queues, all locks in one transaction,
+  nothing held between attempts, `release_lock_series` releases only the locks the series obtained and only the current
+  acquirer's (write: compare-and-delete in one transaction, read: `ZREM` + `DEL`), extended reentrant locks get their
+  ttl back (overview "Lock series").
 - Write-only result shapes stay unchanged; read keys/fields appear only when read data exists.
 - `read_lock_key` is `nil` for write requests; reader data is a data carrier only (the registry decides existence),
   without `acq_id`/`hst_id`; don't store derivable values; a new lock field updates every formatting copy (§2,
@@ -206,7 +210,7 @@ Still in scope (the exemption covers how specs are written, not whether the libr
 - The option: `priority:` in all four lock `Client` methods (default `config['default_lock_priority']`), an Integer
   `MIN_LOCK_PRIORITY..MAX_LOCK_PRIORITY` or a name of `config['lock_priorities']` (the client-wide registry is
   forwarded as the internal keyword `lock_priorities:`, never a public keyword); the name is resolved and the range
-  checked in `AcquireLock` Step 0.1 and before a lock series (`LockSeriesPoC`): code below sees Integers only (RBS
+  checked in `AcquireLock` Step 0.1 and `LockSeries` Step 0.1: code below sees Integers only (RBS
   `RQL::lockPriority` at the boundary, `Integer` below); config validators for both keys, and a name of
   `default_lock_priority` checked against `lock_priorities` by `Config` (after a `configure` block, before a direct `[]=`).
 - Observability: every lock acquirement log line and event (classic, reentrant: the requested priority, lock series:
@@ -256,11 +260,11 @@ Still in scope (the exemption covers how specs are written, not whether the libr
   (`arguments.md#2`, `#10`) and is forwarded by name with shorthand; defaults live only in `Client`, internal
   params are required (`arguments.md#4`); positional order: subject → domain data → observability tail
   `logger, instrumenter, instrument, log_sampling_*, log_sample_this, instr_sampling_*, instr_sample_this`, lock key
-  params `lock_key, read_write_mode, lock_key_queue, read_lock_key_queue, lock_readers_key, read_lock_key, lock_name,
+  params `lock_key, rw_mode, lock_key_queue, read_lock_key_queue, lock_readers_key, read_lock_key, lock_name,
   acquirer_id, host_id, ...`, TTL params `ttl, queue_ttl, lock_index_enabled, lock_index_grace_period`
   (`arguments.md#5`); every call site and the RBS updated with the signature.
 - Operation modules are independent (`acquirer.md#14`): no calls to another `Acquirer::*` module and no references to
-  its RBS types (exceptions: the `AcquireLock` core, `*PoC` modules); shared logic only via `Resource`/`Utilities`;
+  its RBS types (exception: the acquisition core, `AcquireLock` and `LockSeries`); shared logic only via `Resource`/`Utilities`;
   a duplicate keeps the original name and shape with a `NOTE` that it is duplicated on purpose; every copy changes
   in the same change. Don't copy the `WithAcqTimeout` → `LockInfo`/`QueueInfo` debt.
 - New operation: `acquirer/<snake_name>.rb` with one public `class << self` entry named after the file and private
@@ -282,8 +286,7 @@ Still in scope (the exemption covers how specs are written, not whether the libr
   `Exception`: super exceptional cases only, with the reason in the comment; `logic.md#15`). Runtime dependencies:
   `redis-client` only; dev gems in `Gemfile`.
 - `AcquireLock`: new behavior as a new step or mixin with `# Step N.x` numbering and consistent `acq_process` keys
-  (`acquirer.md#10`); `lock_series_poc.rb` is experimental: don't accept new features built on it without the
-  user's request.
+  (`acquirer.md#10`).
 
 ### G. Swarm, Ractors, threads (`swarm.md`)
 - Redis work in stateless class functions shared by the main loop and the manual API (`#1`); main loops build
@@ -300,7 +303,7 @@ Still in scope (the exemption covers how specs are written, not whether the libr
   status shapes `{ running:, state: }` with `'non_initialized'` and their RBS (`#10`).
 
 ### H. Logging and instrumentation (`visitors.md`)
-- Logs/events of `AcquireLock` and its mixins and of `LockSeriesPoC` go through visitor methods (`#1`); mutation
+- Logs/events of `AcquireLock`, `LockSeries` and their mixins go through visitor methods (`#1`); mutation
   modules write one log line and one event inline inside `run_non_critical`, gated by `log_sampled`/`instr_sampled`
   (`acquirer.md#9`).
 - Observability coverage (`logic.md#16`): a new or changed logic that creates/changes/deletes keys without logs and
@@ -313,7 +316,7 @@ Still in scope (the exemption covers how specs are written, not whether the libr
   `instrumenter.notify('redis_queued_locks.<event>', { ... }) rescue nil` with shorthand Symbol keys (`#5`-`#9`).
 - Parameter order: port, sampled flag, extra gates, `lock_key`, data; `rw_mode` after `access_strategy` (logs) or
   after `lock_key` (instrumentation), user `instrument` last (`#6`). `rw_mode` is the requested mode in
-  `AcquireLock`/`TryToLock`/`DequeueFromLockQueue`, the held mode in `YieldExpire`, the series mode in `LockSeriesPoC`.
+  `AcquireLock`/`TryToLock`/`DequeueFromLockQueue`, the held mode in `YieldExpire`, the series mode in `LockSeries`.
 - Sampling decided once per operation (`Logging.should_log?` / `Instrument.should_instrument?`) and passed down (`#7`).
 - Event names and payload keys are public API: no rename/removal without the user's request; no new event on
   the default write success path (`#13`); new or changed log keys/payload keys go to README `## Logging` /
@@ -333,9 +336,11 @@ Still in scope (the exemption covers how specs are written, not whether the libr
 - `# frozen_string_literal: true`; compact constant paths (`module RedisQueuedLocks::Acquirer::Keys`); namespace
   files only `require_relative` (`logic.md#1`).
 - YARD on every class, module, constant, attr and method: `@param`/`@option`/`@return` (`Format: { ... }` for hash
-  results), blank `#`, `@api public|private`, `@since <next>`; behavior/signature changes bump `@version <next>` on
-  the method; the module/class header `@version` changes only with the interface (signatures, added/removed methods,
-  `extend`/`include`/`prepend`, the superclass), never for behavior changes inside the methods (`logic.md#2`).
+  results), blank `#`, `@api public|private`, `@since <next>`; a new `include`/`extend`/`prepend` line has
+  `# @since <next>` right above it (no YARD block; the version that added the mixin); behavior/signature changes bump
+  `@version <next>` on the method; the module/class header `@version` changes only with the interface (signatures,
+  added/removed methods, `extend`/`include`/`prepend`, the superclass), never for behavior changes inside the methods
+  (`logic.md#2`).
 - Comments: `# NOTE:` with `#   - item;` lists, `# Step N.x` in algorithms, `(RW)`/`(lock index)`/`(keyspace)`
   tags, `NOTE: (pipeline layout)`/`(transaction layout)` for positional replies.
 - Redis: uppercase String commands, String numeric args (`'0'`, `'-1'`, `'-inf'`, `'+inf'`), `redis.with do |rconn|`
@@ -399,7 +404,7 @@ Still in scope (the exemption covers how specs are written, not whether the libr
 
 - Confirm it in the code (call sites, copies, RBS, specs), not by pattern match: concurrency claims name the
   interleaving (acquirer A at step X, B at step Y) and why `WATCH` doesn't catch it; layout claims count the
-  commands and positions; mode claims check both `lock_index_enabled` values and both `read_write_mode` values;
+  commands and positions; mode claims check both `lock_index_enabled` values and both `rw_mode` values;
   priority claims check a positive, the default (`0`) and a negative band, a request of another band ahead (alive and
   dead) and requests in both queues.
 - Drop findings contradicted by §5, by a design `NOTE` in the code or by the overview. Mark the rest
@@ -410,7 +415,7 @@ Still in scope (the exemption covers how specs are written, not whether the libr
   - `git grep -n LOCK_INDEX_KEY -- lib`: every use reachable only with `lock_index_enabled` (an `if`/`return unless`
     guard or a lock index lookup branch), except `ReindexLocks` and `Resource`;
   - cross-module calls: `git grep -n "RedisQueuedLocks::Acquirer::" -- lib/redis_queued_locks/acquirer` (only the
-    known `WithAcqTimeout` debt and `LockSeriesPoC` are allowed);
+    known `WithAcqTimeout` debt and the `LockSeries` uses of the `AcquireLock` mixins are allowed);
   - `git diff --name-only <base>` against the `sig/` mirror (§2 exceptions); `git diff --check <base>`.
 - Checks (read-only): a review on request of local changes runs `bundle exec rake rubocop` and
   `bundle exec rbs collection install && bundle exec rake steep:check` (grep the output for `ERROR`/`FATAL`, restore a

data/.ruby-version

@@ -1 +1 @@
-4.0.7
+4.0.9

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 ## [Unreleased]
 
+## [1.23.1] = 2026-11-01
+### Added
+- `timed: true` of `#lock`/`#lock_series`: separate errors of the failures, both are `TimedLockTimeoutError` subclasses: `LockTtlTimeBudgetIsSpentError` (the block was not invoked: no time left) and `TimedBlockExceedsLockTtlError` (the block exceeded the lock TTL);
+### Fixed
+- `timed: true` of `#lock`/`#lock_series`: in some cases the time budget of the block could have been a little bit longer than the lock lifetime (2ms);
+
+## [1.23.0] - 2026-11-01
+### Changed
+- [**Breaking**] `#lock_series`/`#lock_series!` are no longer a proof of concept. The final feature design:
+  - all locks are obtained atomically with the same;
+  TTL, nothing is held while the series waits, any order of the lock names is deadlock-free (see README "lock_series"):
+  - each lock gets exactly `ttl:` (it was `position * (ttl + retry_delay + retry_jitter)`);
+  - `timeout:`, `retry_count:` and `queue_ttl:` limit the whole series (they limited each lock of the series);
+  - a series without a block returns `{ ok: true, result: { lock_series:, rql_lock_series:, acq_id:, hst_id:, ts:, ttl: } }` (it returned `nil`);
+  - a failed series has empty `acquired_locks:` and all locks in `missing_locks:`, `failed_on_lock:` can be `nil`;
+  - the events and logs of `#lock` are not raised for the locks of the series: they are replaced by the `lock_series_*` events of each lock
+    (`log_lock_try` logs stay per lock);
+  - the messages of the retry limit and timeout errors name the series and the lock that blocks it;
+  - an empty series raises `RedisQueuedLocks::ArgumentError`, duplicated lock names are one lock;
+  - upgrade all processes that share these locks: older versions obtain a series lock by lock;
+- [**Breaking**] `read_write_mode:` option of `#lock`/`#lock!`/`#lock_series`/`#lock_series!`/`#extend_lock_ttl` is renamed to `rw_mode:`;
+### Added
+- `#lock_series` instrumentation events and logs: `lock_series_obtaining_failed` of the series and the events of each lock of the series:
+  `lock_series_intermediate_lock_obtained`, `lock_series_lock_obtained`, `lock_series_lock_obtaining_failed`;
+- `reentrant_lock_keys` key of the `lock_series_obtained` and `lock_series_hold_and_release` events and logs;
+- the logs of the series acquirement: `start_try_to_lock_series_cycle`, `dead_score_reached__reset_series_position`,
+  `dequeue_from_lock_series_queues`, `decrease_lock_series`;
+- RBS signatures of `#lock_series`/`#lock_series!`;
+
 ## [1.22.0] - 2026-10-27
 ### Added
 - *Brand New Feature*: **Lock Request Prioritization**: the `priority:` option of `#lock`/`#lock!`/`#lock_series`/`#lock_series!`
@@ -168,7 +197,7 @@
 ## [1.16.0] - 2026-01-27
 ### Added
 - Brand new Feature **"Lock series of locks"**
-  - (*Proof of Concpet*-based implementation at the moment) 
+  - (*Proof of Concpet*-based implementation at the moment)
   - lock series of lock simultainously (and release them all at the finish of your the invocation of block of code under the obtained locks);
   - exmaple: `client.lock_series("a", "b", "c")` (or in exceptional-based way `client.lock_series!("a", "b", "c")`;
 ### Changed

data/CLAUDE.md

@@ -13,10 +13,11 @@ Full details (config keys, key layout, events, errors, stack, CI): `.claude/proj
 - `acquirer/*.rb`: one stateless module per operation (`class << self`), returns `{ ok:, result: }`; `!` client methods raise.
 - `acquirer/acquire_lock.rb`: composed via `extend` mixins in `acquire_lock/` (try_to_lock, with_acq_timeout, delay_execution, dequeue_from_lock_queue, yield_expire) + `LogVisitor`/`InstrVisitor` event hooks.
 - Locking: `ZADD NX` into the request queue, then WATCH/MULTI; Lua only for write TTL extension/decrease.
-- Lock request priorities (`priority:` -100..100 or a priority name of `config['lock_priorities']`, resolved to its Integer in `AcquireLock` Step 0.1 and before a lock series; `config['default_lock_priority']`): queue score = enqueue time - priority * 2**32 (`Resource.calc_initial_acquirer_position`), strict priority + FIFO inside a priority; dead requests are pruned per priority band (never one `-inf..now-ttl` range): the own band on each queueing, the bands of the dead requests that block the attempt (the write queue head, the earlier opposite-mode request) in one more round trip (`TryToLock#drop_dead_requests_ahead`, band and liveness decoded from the score); the attempt cost never depends on the priority range; every lock acquirement log/event carries the Integer `priority`. Component map: overview "Lock request prioritization in the architecture"; details: overview "Lock request priorities".
-- Read/Write locks (`read_write_mode: :write|:read`): write lock `rql:lock:<name>` + queue `rql:lock_queue:<name>`; readers registry `rql:lock_readers:<name>` (ZSET acq_id => Redis-time expiry), read queue `rql:lock_read_queue:<name>`, per-reader data `rql:lock_reader:<name>:<acq_id>`. Readers WATCH the write key only, writers WATCH the write key + registry; queues give ordering only. Component map: overview "Read/Write locks in the architecture"; details: overview "Read/Write locks".
+- Lock request priorities (`priority:` -100..100 or a priority name of `config['lock_priorities']`, resolved to its Integer in `AcquireLock` Step 0.1 and `LockSeries` Step 0.1; `config['default_lock_priority']`): queue score = enqueue time - priority * 2**32 (`Resource.calc_initial_acquirer_position`), strict priority + FIFO inside a priority; dead requests are pruned per priority band (never one `-inf..now-ttl` range): the own band on each queueing, the bands of the dead requests that block the attempt (the write queue head, the earlier opposite-mode request) in one more round trip (`TryToLock#drop_dead_requests_ahead`, band and liveness decoded from the score); the attempt cost never depends on the priority range; every lock acquirement log/event carries the Integer `priority`. Component map: overview "Lock request prioritization in the architecture"; details: overview "Lock request priorities".
+- Read/Write locks (`rw_mode: :write|:read`): write lock `rql:lock:<name>` + queue `rql:lock_queue:<name>`; readers registry `rql:lock_readers:<name>` (ZSET acq_id => Redis-time expiry), read queue `rql:lock_read_queue:<name>`, per-reader data `rql:lock_reader:<name>:<acq_id>`. Readers WATCH the write key only, writers WATCH the write key + registry; queues give ordering only. Component map: overview "Read/Write locks in the architecture"; details: overview "Read/Write locks".
 - Lock lookup modes: `config['lock_index_enabled']` (client-wide, `false` by default) is read by `Client`/`Swarm` and passed to every lock-iterating module (swarm, `locks`, `queues`, `keys`, `clear_*`) and to the hot path; each module keeps the keyspace lookup (one `SCAN` pass, the pre-index code) and the lock index lookup (one `ZSCAN` pass) side by side with the shared processing in one copy.
 - Lock index `rql:index:locks` (enabled mode only; ZSET lock name => upper bound of the lifetime of all lock keys, client ms + ttl + `lock_index_grace_period`): every key-creating command is followed by `ZADD GT` (queueing pipeline, obtaining `MULTI`), every extension by `ZADD XX INCR`, names are removed only with all their keys (`unlock`, `clear_locks`), queues have TTL, expired names are pruned on queueing; lock index commands are conditional tails of their pipelines/transactions (none in the disabled mode); `reindex_locks` (one keyspace `SCAN`, both modes) adopts keys without entries after enabling. Details: overview "Lock index".
+- Lock series (`acquirer/lock_series.rb`, `lock_series/`): all locks obtained by one WATCH/MULTI attempt with one `ttl` (all or nothing, nothing held while waiting), one queue position in all queues of the series (deadlock-free for any order of names), limits of the whole series; details: overview "Lock series".
 - Strategies: `access_strategy` `:queued`|`:random`; `conflict_strategy` `:wait_for_lock`|`:work_through`|`:extendable_work_through`|`:dead_locking`.
 - `resource.rb`: all key names and acquirer/host IDs. `config.rb`: `setting`/`validate` DSL, read as `config['a.b']`.
 - `swarm/`: zombie-lock cleanup. `Supervisor` thread revives `ProbeHosts` (`SwarmElement::Threaded`) and `FlushZombies` (`SwarmElement::Isolated`, Ractor talking via `Ractor::Port`s); each element runs a main-loop thread with its own Redis connection.
@@ -27,10 +28,10 @@ Full details (config keys, key layout, events, errors, stack, CI): `.claude/proj
 Detailed, path-scoped rules in `.claude/rules/`: `logic.md` (lib, general), `acquirer.md` (acquirer modules, Redis access), `visitors.md` (log/instrumentation visitors), `arguments.md` (long keyword lists), `swarm.md` (swarm supervisor/elements, Ractor/Thread rules), `tests.md` (spec), `type-checking.md` (sig/Steep), `changelog.md` (CHANGELOG entries), `git.md` (commit messages and commit flow, always loaded).
 - Long explicit keyword/parameter lists are intentional (minimal allocations, signature-as-DSL): never introduce parameter objects, option structs or `**opts`; add new options as explicit keywords to every `Client` variant and forward them by name.
 - Update the matching `sig/*.rbs` for every `lib/` change; keep Steep green.
-- Keep `# frozen_string_literal: true` and YARD `@api`/`@since`/`@version` tags (class/module `@version` changes only with the interface: signatures, added/removed methods, `extend`/`include`/`prepend`, the superclass; `logic.md#2`).
+- Keep `# frozen_string_literal: true` and YARD `@api`/`@since`/`@version` tags (`# @since` right above each `include`/`extend`/`prepend` line; class/module `@version` changes only with the interface: signatures, added/removed methods, `extend`/`include`/`prepend`, the superclass; `logic.md#2`).
 - `{ ok:, result: }` is for the public API only (`Client`, `Acquirer::*`, `Swarm` facade actions). Internal swarm element APIs (commands, replies, helpers) use bare scalars/primitives (see `swarm.md`).
 - New operation: `Acquirer::*` module, thin `Client` method (+ `!` variant), RBS, spec.
-- Operation modules behind `Client` methods (all `Acquirer::*` except the `AcquireLock` acquisition core and PoC modules such as `LockSeriesPoC`, which may reuse other modules) are independent: they never call each other or reference each other's RBS types, share logic only via `Resource`/`Utilities`, and duplicate similar logic on purpose (independence over DRY; e.g. `Locks` duplicates the `LockInfo` formatting). Details: `acquirer.md`.
+- Operation modules behind `Client` methods (all `Acquirer::*` except the lock acquisition core: `AcquireLock` and `LockSeries`, which reuses the `AcquireLock` mixins) are independent: they never call each other or reference each other's RBS types, share logic only via `Resource`/`Utilities`, and duplicate similar logic on purpose (independence over DRY; e.g. `Locks` duplicates the `LockInfo` formatting). Details: `acquirer.md`.
 - New option: `setting` (+ `validate`) in `config.rb` + its `Config#[]` overload line in `sig/redis_queued_locks/config.rbs` (typed per key).
 - Dev gems go in `Gemfile`, not the gemspec.
 - Commits (`git.md`): subject only `[<scope>] <summary>` (several features: 1-2 words each, comma-separated), no body; when a step is complete (requirement fully implemented, specs/rubocop/steep green), and only then, run the `rql-code-review` skill on the uncommitted changes, then ask before committing, with the proposed subject, a recap of the changes and the review verdict; an explicit "commit" request needs no extra question and no review (a commit authorized in advance for a task still gets the review); never on `master`, never push.