redis_queued_locks 1.20.0 → 1.22.0

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

@@ -1,13 +1,13 @@
 ---
 name: rql-code-review
-description: Code review of redis_queued_locks changes against the project's own invariants and conventions (WATCH/MULTI lock safety, read/write key families, the lock index superset invariant in both lookup modes, one-pass iteration, operation-module independence, long explicit argument lists, log/instrumentation visitors, RBS/Steep, docs sync). Use when the user asks to review / code-review (ревью, код-ревью, проверь изменения) a branch, diff, commit range, PR, staged changes or files of this repository. Also run it automatically on the uncommitted changes when a task in this repository is done and ready to commit, right before asking about the commit (never earlier). Spec files (*_spec.rb) are exempt from style/principle checks until the suite rework; only the coverage of the changed library behavior is checked.
+description: Code review of redis_queued_locks changes against the project's own invariants and conventions (WATCH/MULTI lock safety, read/write key families and the order between modes, lock request priority bands and their head-driven dead request cleanup, the lock index superset invariant in both lookup modes, one-pass iteration, operation-module independence, long explicit argument lists, log/instrumentation visitors, RBS/Steep, docs sync). Use when the user asks to review / code-review (ревью, код-ревью, проверь изменения) a branch, diff, commit range, PR, staged changes or files of this repository. Also run it automatically on the uncommitted changes when a task in this repository is done and ready to commit, right before asking about the commit (never earlier). Spec files (*_spec.rb) are exempt from style/principle checks until the suite rework; only the coverage of the changed library behavior is checked.
 argument-hint: "[uncommitted | base..head | <commit> | pr <N> | staged | <paths...>]"
 ---
 
 # redis_queued_locks code review
 
 Review a change of this gem the way its maintainer does: lock safety first, then the project invariants
-(read/write locks, lock index, iteration), then architecture, types, docs and style. The rules live in
+(read/write locks, lock request priorities, lock index, iteration), then architecture, types, docs and style. The rules live in
 `CLAUDE.md`, `.claude/project-overview.md` and `.claude/rules/*.md`; this skill says what to check, where the
 details are, and what must not be reported.
 
@@ -28,7 +28,7 @@ details are, and what must not be reported.
   - Scope `uncommitted`: the changes of the step (earlier steps are reviewed before their own commits).
   - The completion checks have just run: report their results, don't re-run them. A step without code changes (docs,
     `.claude` files) gets a docs review only: accuracy against the code, the overview and the rules, cross-file
-    consistency (§4 J).
+    consistency (§4 K).
   - Blocker/Major findings in the step's own changes mean the step is not complete: fix them as part of the task (the
     review itself stays read-only), re-run the affected checks and review the fixed hunks once more; findings that
     need the user's decision, or remain after that pass, are reported instead of the commit question (`git.md#9`).
@@ -56,7 +56,8 @@ details are, and what must not be reported.
 ## 2. Context to load before judging
 
 Read the rule files of the touched paths and the overview sections of the touched topics (lock flow, "Read/Write
-locks", key layout, "Lock index", lock lookup modes, events, errors, conventions):
+locks in the architecture" + "Read/Write locks", "Lock request prioritization in the architecture" + "Lock request
+priorities", key layout, "Lock index", lock lookup modes, events, errors, conventions):
 
 | Changed path | Rule files |
 |---|---|
@@ -67,6 +68,7 @@ locks", key layout, "Lock index", lock lookup modes, events, errors, conventions
 | `logging/**`, `instrument/**` | + `visitors.md` |
 | `sig/**`, `Steepfile`, `rbs_collection.yaml` | `type-checking.md` |
 | `spec/**` | `tests.md` (coverage expectations only, see §3) |
+| `CHANGELOG.md` | `changelog.md` |
 | commits / messages | `git.md` |
 
 - Read every changed method in full, its callers, its RBS signature and every copy of duplicated logic. Copies
@@ -80,16 +82,24 @@ locks", key layout, "Lock index", lock lookup modes, events, errors, conventions
   - `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`;
+  - 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 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 exceptions: `acquirer.rb` → `sig/redis_queued_locks/acquier.rbs`;
-  `acquire_lock/yield_expire/log_visitor.rb` → `sig/.../acquire_lock/yield_with_expire/log_visitor.rbs`;
-  `lock_series_poc*` has no RBS.
+- Mirror path exception: `lock_series_poc*` has no RBS.
 - 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/`: the typo `@since 19.0.0` wins it.
-  A value older than `VERSION` on new code, or a behavior change without a `@version` bump, is a Minor finding.
+  `RedisQueuedLocks::VERSION` (`version.rb`); don't take the maximum over `lib/` (old tags can be wrong).
+  A value older than `VERSION` on new code, a method behavior/signature change (a typo fix in the method or keyword
+  argument name included; a renamed positional parameter is not a signature change) without the method `@version` bump, or a
+  class/module header `@version` that does not match its latest interface change (`logic.md#2`: signatures,
+  added/removed methods, `extend`/`include`/`prepend`, the superclass; behavior changes never bump the header) is a
+  Minor finding.
 
 ## 3. Spec files are exempt (until the suite rework)
 
@@ -140,15 +150,31 @@ Still in scope (the exemption covers how specs are written, not whether the libr
   the reentrant write extension check `result.size == (lock_index_enabled ? 5 : 4)` follows its `MULTI`.
 - Round trips of the hot path must not regress silently (overview "Lock acquisition flow"): `lock {}` = 4, a
   failed attempt = 3, a failed retry = 1 (pre-check), `fail_fast` on an obtained lock = 1, `unlock` without
-  readers = 1. Independent reads share one `pipelined` round trip (also inside `multi(watch:)`).
+  readers = 1; the only extra round trips are the dead blocking request removals of Step 2.2 (one per removal, none
+  while nothing dead blocks). Independent reads share one `pipelined` round trip (also inside `multi(watch:)`).
 - New destructive paths (delete/shorten a lock) check the owner, unless the change documents the trade-off as
   accepted by the user (like the known limitations in §5).
 - Shared mutable state behind `Utilities::Lock#synchronize` (`logic.md#9`).
 
-### B. Read/write awareness (`logic.md#13`, `acquirer.md#12`)
+### B. Read/write awareness (`logic.md#13`, `acquirer.md#12`, overview "Read/Write locks in the architecture")
 - Every operation over locks, queues, zombies or lock info covers `rql:lock:*`, `rql:lock_queue:*`,
-  `rql:lock_readers:*`, `rql:lock_read_queue:*` and `rql:lock_reader:<name>:<acq_id>`; every attempt prunes dead
-  requests in both queues; dequeue/cleanup removes the request from the queue of its mode.
+  `rql:lock_readers:*`, `rql:lock_read_queue:*` and `rql:lock_reader:<name>:<acq_id>`; every attempt prunes the dead
+  requests of its priority band in both queues (and the bands of the dead requests that block it, §4 C);
+  dequeue/cleanup removes the request from the queue of its mode.
+- Order between modes (`:queued`, `find_opposite_request_ahead`/`lock_obstacle`, shared by the attempt and the
+  pre-check): a write request must be the head of the write queue and have no earlier read request, a read request
+  must have no earlier write request ("earlier" = the `(score, acq_id)` comparison on the shifted scores); the
+  order never decides mutual exclusion.
+- The held mode decides the release: `acquire_lock` keeps the try result `rw_mode` as `held_rw_mode` for
+  `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
+  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`).
 - 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,
@@ -157,7 +183,41 @@ Still in scope (the exemption covers how specs are written, not whether the libr
   entries) is still read correctly; a key/data format change states the rolling-deploy requirement in README and
   CHANGELOG.
 
-### C. Lock index, both lookup modes (`acquirer.md#16`, overview "Lock index")
+### C. Lock request priorities (`acquirer.md` "Lock request priorities", overview "Lock request prioritization in the architecture")
+- Queue scores only through `Resource` (the single source of the layout): `calc_initial_acquirer_position(priority)`
+  (enqueue time - `priority * LOCK_PRIORITY_BAND`), the requeue check `dead_score_reached?(position, priority, ttl)`
+  (a requeued request goes to the end of its own band), decoding with `lock_request_priority(score)`; no raw
+  `Time.now.to_f` positions, no own band arithmetic outside `Resource`.
+- Dead request pruning per band only: `ZREMRANGEBYSCORE <queue> <lock_priority_band_floor(p)>
+  <lock_priority_band_dead_score(dead_score, p)>`; a new `-inf .. now - ttl` range on a request queue is a Blocker
+  (it drops alive higher-priority requests and keeps dead lower-priority ones); full clears (`-inf .. +inf`) and
+  member removals (`ZREM`) are band-independent; `-inf .. -inf` drops the requests at `-inf` only (manual writes:
+  always dead, out of all bands; `+inf` is never dead), and decoding an infinite score must never raise
+  (`lock_request_priority` maps `-inf`/`+inf` to the range bounds).
+- Head-driven cleanup, cost independent of the priority range: the queueing prunes the own band in both queues (in
+  its pipeline, before `ZADD NX`: a requeued request must not lose its new position to the removal of its old one),
+  Step 2.2 (`drop_dead_requests_ahead`, attempt and pre-check, `:queued` only) drops the bands of the
+  dead blocking requests (the write queue head for writers, the earlier opposite-mode request) with the queue heads
+  re-read in the same round trip, bounded by `MAX_DEAD_REQUEST_REMOVALS`; `ClearDeadRequests` prunes only the bands
+  whose first request is dead. Never enumerate the priority range per attempt or per queue; any band is decoded
+  (also out of the range: newer versions).
+- Ordering uses the shifted scores as is (queue heads, the cross-mode `(score, acq_id)` comparison): strict priority
+  between bands, FIFO inside a band, the same in both modes; the priority never takes part in mutual exclusion.
+- 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
+  `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:
+  the series priority, `lock_obtaining_failed`) carries the Integer `priority` right after `rw_mode`; try-lock logs
+  that name another request carry its decoded priority (`first_priority_in_queue`, `ahead_priority`, `dead_priority`)
+  computed at the call site only when `log_sampled && log_lock_try` (one helper: `TryToLock#logged_request_priority`); info results carry `'priority'` (every copy).
+- Compatibility: priority `0` keeps the raw timestamp scores of older versions/data; a change of the score layout or
+  of the pruning states the rolling-deploy effect in README and CHANGELOG (older versions prune positive-priority
+  requests as dead ones).
+
+### D. Lock index, both lookup modes (`acquirer.md#16`, overview "Lock index")
 - Disabled mode (default): no lock index command at all (`LOCK_INDEX_KEY` only under `if lock_index_enabled` /
   after `return unless lock_index_enabled`), no `ZSCAN`, queues without TTL. Enabled mode: no keyspace `SCAN`
   except `ReindexLocks`.
@@ -174,9 +234,9 @@ Still in scope (the exemption covers how specs are written, not whether the libr
   `lock`, `lock!`, `lock_series`, `lock_series!`, `reindex_locks`. Pruning (`ZREMRANGEBYSCORE <index> -inf
   <now - 1>`) stays in the queueing pipeline, `flush_zombies`, `clear_locks`, `clear_dead_requests`.
 
-### D. Iteration and performance (`acquirer.md#7`, `arguments.md#7`)
+### E. Iteration and performance (`acquirer.md#7`, `arguments.md#7`)
 - One pass per operation: one `SCAN` over `KEY_PATTERN`/`ALL_LOCK_QUEUES_PATTERN` classified by
-  `Resource.lock_key_family`, or one `ZSCAN` via `each_lock_name_batch` (expired scores skipped). Never `KEYS`,
+  `Resource.lock_key_family`, or one `ZSCAN` via `each_lock_name_batch` (expired scores skipped by `Resource.lock_index_score_expired?`: the `"inf"` score never expires). Never `KEYS`,
   never one round trip per key; per-key commands in pipelined batches collected across pages, plus the
   remainder batch.
 - A new lock-iterating operation implements both lookups side by side, chooses the lookup in one place
@@ -188,7 +248,7 @@ Still in scope (the exemption covers how specs are written, not whether the libr
   `NO_LOCK_DATA`); keys computed once in `acquire_lock`; log-only Redis reads gated at the call site
   (`acquirer.md#13`); no `Set` splatted in a loop.
 
-### E. Architecture and API design
+### F. Architecture and API design
 - `Client` only fills defaults from `config['...']` and delegates (`logic.md#3`); an `x!` variant exists only when it
   must raise and repeats the full keyword list.
 - No parameter objects, `Struct`/`Data.define`/`OpenStruct`, builders, `**opts`, `options = {}`, `...` forwarding
@@ -214,14 +274,18 @@ Still in scope (the exemption covers how specs are written, not whether the libr
   key / acquirer id in the message.
 - Keys only via `Resource.prepare_*`, `*_PATTERN`, `SWARM_KEY`, `LOCK_INDEX_KEY` (`logic.md#5`): flag every new
   `'rql:...'` literal outside `resource.rb`.
-- Config: `setting` + `validate` in `config.rb` (booleans `val == true || val == false`, Integers with ranges), dotted
-  keys for groups, unit in a trailing `# NOTE:` comment, read as `config['key']` (`logic.md#7`). Errors:
-  `class XError < Error; end` in `errors.rb`. Runtime dependencies: `redis-client` only; dev gems in `Gemfile`.
+- Config: `setting` + `validate` in `config.rb` (booleans `val == true || val == false`, Integers with ranges; per-call
+  numeric options validated with the same ranges in the operation module, `logic.md#7`), dotted
+  keys for groups, unit in a trailing `# NOTE:` comment, read as `config['key']` (`logic.md#7`), one typed
+  `Config#[]` overload line per key in `config.rbs` (`type-checking.md#12`). Errors:
+  `class XError < Error; end` in `errors.rb`, each under the global base of its branch (`Error`, `ArgumentError`,
+  `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.
 
-### F. Swarm, Ractors, threads (`swarm.md`)
+### 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
   their own client with `RedisClientBuilder` inside the loop thread (`#4`).
 - Into `Ractor.new` only copied plain values (`config.slice(...)`, scalars, `lock_index_enabled`): no `rql_client`,
@@ -235,9 +299,14 @@ Still in scope (the exemption covers how specs are written, not whether the libr
 - Lifecycle names and semantics identical in both bases (`#7`); a new element is registered everywhere (`#3`);
   status shapes `{ running:, state: }` with `'non_initialized'` and their RBS (`#10`).
 
-### G. Logging and instrumentation (`visitors.md`)
-- Logs/events of `AcquireLock` and its mixins and of `LockSeriesPoC` go through visitor methods (`#1`); release
-  modules call `instrumenter.notify` inline inside `run_non_critical`, gated by `instr_sampled` (`acquirer.md#9`).
+### H. Logging and instrumentation (`visitors.md`)
+- Logs/events of `AcquireLock` and its mixins and of `LockSeriesPoC` 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
+  instrumentation, a mutation event/log that times an internal part instead of the whole root operation, a mutation
+  payload without `instrument`, a `Client` mutation method without the observability keywords, or instrumented lock
+  info queries are findings; the swarm elements are known debt.
 - Visitor shape: `class << self`, method name = event name (`__` between phase and detail), same name in the
   Log and Instr visitors, first line `return unless log_sampled` (`&& log_lock_try` for `TryToLock` steps), one
   `logger.debug do ... end rescue nil` with `"[redis_queued_locks.<event>] "` and `key => 'value'` pairs, or
@@ -250,7 +319,7 @@ Still in scope (the exemption covers how specs are written, not whether the libr
   the default write success path (`#13`); new or changed log keys/payload keys go to README `## Logging` /
   `### Instrumentation Events` and CHANGELOG (`#14`).
 
-### H. Types (`type-checking.md`)
+### I. Types (`type-checking.md`)
 - Every changed method, param, return shape, constant or ivar is mirrored in `sig/` (`#1`): nested module blocks,
   `use RedisQueuedLocks as RQL` / `use RedisClient as RC`, shared types (`RC::client`, `RQL::loggerObj`,
   `RQL::instrObj`, `samplerObj`), `type xxxResult = { ok: bool, result: ... }` for public results, literal types for
@@ -260,12 +329,13 @@ Still in scope (the exemption covers how specs are written, not whether the libr
   annotation carries `NOTE: (steep)`; never shape runtime code around Steep (`#5`). `Steepfile` is never loosened (`#6`).
 - RBS must match runtime values (runtime type checks run the suite): e.g. `Integer|Float` where a Float can arrive.
 
-### I. Ruby style of the codebase
+### J. Ruby style of the codebase
 - `# 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 changes bump `@version <next>` on the
-  method and on the module/class header (`logic.md#2`).
+  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`).
 - 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|`
@@ -281,12 +351,16 @@ Still in scope (the exemption covers how specs are written, not whether the libr
 - Rubocop: only specific `Metrics`/`Layout` cops disabled locally with a paired `enable`, never
   `# rubocop:disable all` in new code (`logic.md#10`); long signatures are not "fixed" (`arguments.md#8`).
 - Suggestions only (`logic.md` recommendations, not violations): correctly spelled new identifiers (don't copy the
-  known typos), `then` instead of `yield_self` in new code.
+  known typos).
 
-### J. Docs and process
+### K. Docs and process
 - The same change updates `.claude/project-overview.md` and the affected `.claude/rules/*.md` for every new/changed
   key, option, result shape, event, algorithm step or limitation (`logic.md#12`), README and CHANGELOG
   `[Unreleased]` for user-visible behavior, and the YARD of the touched `Client` methods.
+- CHANGELOG entries are compact (`changelog.md`): one 1-2 line bullet per subject-level change, no implementation
+  details (algorithm steps, Redis commands, round trips, internals, full event lists), no entries for internal-only
+  changes; one entry per feature, released sections untouched; a fundamentally new feature or globally new support
+  (Read/Write locks, Lock Index, Garnet support) is a separate `*Brand New Feature*` entry first in `### Added`.
 - Commits under review (`git.md`): subject only `[<scope>] <summary>`, lowercase, imperative, no trailing period,
   no body except the attribution trailer, never on `master`.
 
@@ -297,13 +371,24 @@ Still in scope (the exemption covers how specs are written, not whether the libr
   read→write upgrade as an error unless `:wait_for_lock`; nested reads through `conflict_strategy`; no fairness
   between modes with `:random`; best-effort cross-host FIFO; no Lua in the RW path; one mode per lock series;
   `lock_index_enabled` as a config-only mode; the lock index defaulting to `false`.
+- Settled design of the lock request priorities (overview "Lock request priorities", limitations kept by the user):
+  strict priority (lower priorities can starve within their timeout/retry limits), no preemption of an obtained lock,
+  the polled handoff (`retry_delay`), dead requests pruned with the pruner's `queue_ttl`, dead requests of lower bands
+  lingering until an attempt of their band/`clear_dead_requests`/the queue TTL/the swarm (they never block), the
+  library-constant range `-100..100` and its ~61 µs FIFO precision inside a band, `MAX_DEAD_REQUEST_REMOVALS` per
+  attempt, `:random` requests ignoring the order and the priorities of other requests (while their own requests are queued
+  at their priority: `:queued` requests wait for them), `clear_dead_requests` reading the batch queues (2 round trips per batch; `by_priority: true`: the first
+  request of each band only, the most bands of a batch queue + 1 round trips),
+  the order degradation with older versions (no safety impact), the queue score as the only order and liveness of a request
+  (a separate liveness registry of request deadlines was rejected by the user: don't propose it).
+- Unused `Resource` methods marked `# NOTE: (debug)` (manual runtime checks, `logic.md#17`); report a debug method
+  only when it is wrong for a key family it can get.
 - Known limitations kept by the user: `YieldExpire` write release (`EXPIRE 0`) and ttl decrease without an owner
   check; `HMGET`→`DEL` without `WATCH` in `ReleaseLocksOf`/`FlushZombies`; `unlock` dropping the data of a reader
   re-acquired between its two round trips; `zombie_acquirers` vs `flush_zombies` acquirer sets.
-- Known debt: `WithAcqTimeout` → `LockInfo`/`QueueInfo`; rspec-retry, disabled coverage minimum, non-blocking runtime
-  type checks; `acquier.rbs` and the `yield_with_expire` RBS path; typos `swarm_element__termiante`,
-  `@api ppublic`/`pulic`/`pub;ic`, `@since 19.0.0`; `sleep(0.1)` readiness waits and missing logging in the swarm;
-  one flusher per process; `EVAL` without `SCRIPT LOAD`; `# rubocop:disable all` around lock series.
+- Known debt: `WithAcqTimeout` → `LockInfo`/`QueueInfo`; rspec-retry, disabled coverage minimum;
+  `sleep(0.1)` readiness waits and missing logging in the swarm;
+  one flusher per process; `EVAL` without `SCRIPT LOAD`.
 - "Recommendations (proposed, not yet project policy)" in the rule files: never violations; mention one only as an
   optional suggestion for touched code.
 - Pre-existing problems outside the diff: out of scope; mention a severe one briefly in the template's
@@ -314,7 +399,9 @@ 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 `read_write_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
   `CONFIRMED` (traced end to end) or `PLAUSIBLE` (depends on an assumption: name it).
 - Helpful greps:
@@ -328,8 +415,10 @@ Still in scope (the exemption covers how specs are written, not whether the libr
 - 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
   rewritten `rbs_collection.lock.yaml` with `git checkout -- rbs_collection.lock.yaml`); the automatic pre-commit run
-  reports the completion checks instead of re-running them (see "When to run"). Don't run `rake rspec` without
-  asking: it needs a local Redis, `FLUSHDB`s db 0 and db 1 and takes ~6 minutes.
+  reports the completion checks instead of re-running them (see "When to run"). Don't run the specs without
+  asking: they need a local Redis; when asked, run them in parallel processes (`rake rspec:parallel`: ~1 minute,
+  flushes db `0..2n-1` for `n` workers; the serial `rake rspec`, ~6 minutes and db 0/1, only for the one-process checks
+  of `tests.md#1`).
 
 ## 7. Report
 
@@ -361,11 +450,13 @@ Both templates have the same structure: change them together. A new language = a
 same structure plus a row in the table above.
 
 ### Severity and order
-- Blocker: breaks mutual exclusion or the lock index superset, loses or leaks locks/data, crashes, breaks the public
-  API (method, result shape, event, config key) or turns CI red.
-- Major: a rule violation with a real consequence: a missed read key family or lookup mode, per-key round trips, a
-  hot-path regression, broken module independence, a missing RBS/docs update for a changed contract, new
-  behavior without specs.
+- Blocker: breaks mutual exclusion or the lock index superset, loses or leaks locks/data (e.g. a queue pruning that
+  drops alive requests of another priority band), crashes, breaks the public API (method, result shape, event,
+  config key) or turns CI red.
+- Major: a rule violation with a real consequence: a missed read key family or lookup mode, a broken order between
+  modes or priorities, a release of the wrong (requested instead of held) mode, a dead request that can block a
+  queue, a cost that grows with the priority range, per-key round trips, a hot-path regression, broken module
+  independence, a missing RBS/docs update for a changed contract, new behavior without specs.
 - Minor: convention deviations with little impact (YARD tags, comment format, naming, idioms).
 - Nit: optional polish.
 - Order by severity, then by file. Empty sections are omitted; with no findings the verdict says so and the sync and

data/CHANGELOG.md

@@ -1,140 +1,120 @@
 ## [Unreleased]
 
+## [1.22.0] - 2026-10-27
+### Added
+- *Brand New Feature*: **Lock Request Prioritization**: the `priority:` option of `#lock`/`#lock!`/`#lock_series`/`#lock_series!`
+  (`-100..100`, `0` by default) orders the waiting `:queued` lock requests of both modes: strict priority, FIFO inside
+  a priority; the obtained lock is never taken away (see README "Lock Request Prioritization"):
+  - `config['default_lock_priority']`: the default priority of the client;
+  - priority names: `config['lock_priorities']` (`:lowest`, `:low`, `:normal`, `:high`, `:highest` by default, custom names
+    allowed), accepted by `priority:` and `config['default_lock_priority']`;
+  - `#clear_dead_requests`: drops the dead lock requests of all priorities; the new `by_priority:` option reads only the first
+    lock request of each priority (long lock queues with few priorities);
+  - the new `log_lock_try` log `[redis_queued_locks.try_lock.dead_request_removed]`;
+  - upgrade all processes that share locks before using positive priorities: older versions drop such lock requests as dead
+    ones (the order breaks, the mutual exclusion is not affected);
+### Changed
+- `#queue_info`/`#queues_info`: each lock request has the `"priority"` field;
+- the lock acquirement logs and instrumentation events carry the Integer `priority`, the try-lock logs that name another lock
+  request carry its priority (see README `## Logging` / `### Instrumentation Events`);
+- RBS: `RedisQueuedLocks::Config#[]` is typed per config key (unknown keys are type errors, dynamic `String` keys no longer
+  type-check);
+- RBS: `read_write_mode`, `access_strategy` and `conflict_strategy` of `Client` are typed as literal unions;
+### Fixed
+- a lock request requeued after waiting longer than its `queue_ttl` could lose its next attempt (a spent retry);
+- the enabled lock index: locks without TTL adopted by `#reindex_locks` were skipped by all lock-iterating operations;
+
+## [1.21.0] - 2026-10-13
+### Added
+- Logging and instrumentation of all operations that change Redis keys (the swarm is not covered yet; see README `## Logging` /
+  `### Instrumentation Events`):
+  - the `redis_queued_locks.lock_obtaining_failed` event and log (with the failure `result`);
+  - the `redis_queued_locks.extend_lock_ttl`, `redis_queued_locks.clear_dead_requests` and `redis_queued_locks.reindex_locks`
+    events and logs;
+  - logs of the existing `explicit_lock_release`, `explicit_read_lock_release`, `explicit_all_locks_release` and
+    `release_locks_of` events;
+  - `#reindex_locks`: `logger:`, `instrumenter:`, `instrument:` and the log/instrumentation sampling options;
+### Changed
+- stricter validation: invalid values raise `RedisQueuedLocks::ArgumentError` (`RedisQueuedLocks::SwarmArgumentError` for
+  the swarm methods, `RedisQueuedLocks::ConfigValidationError` for the config) instead of a silent misbehavior:
+  - `ttl` of the lock methods and `milliseconds` of `#extend_lock_ttl`: positive `Integer`s;
+  - the per-call numeric options: `Integer`s in the ranges of their config keys (`Float`s like `timeout: 0.5` are rejected);
+  - the config: positive `Integer` TTLs, periods and batch/scan sizes;
+  - `:meta`: reserved lock data keys are rejected as Symbol keys too;
+- the internal timeout errors of `timed: true` and `timeout` are not `StandardError`s anymore: `rescue => e` /
+  `rescue Timeout::Error` inside the block does not catch them (the public errors and results are the same);
+### Fixed
+- write locks with a non-positive `ttl` were reported as obtained without the mutual exclusion;
+- non-positive config and per-call values broke the operations (endless `:dead_score_reached`, failing scans, stopped swarm
+  loops, all hosts as zombies, `#extend_lock_ttl` shortening the lock, `#lock_series` locks with a near-zero ttl);
+- Symbol keys of `:meta` overwrote the reserved lock data (broken reentrant locks, owner checks and lock info);
+- a `rescue` inside a `timed` block or in a logger/instrumenter swallowed the lock timeouts: the block could run past
+  the lock TTL, the acquirement timeout could be lost;
+- a connection interrupted inside `WATCH` (lock timeouts, `Timeout.timeout` of your code) could abort the next transaction
+  on it (e.g. a lock release); it is closed now;
+- the `instrument:` option of `#unlock`, `#clear_locks`, `#clear_locks_of`/`#clear_current_locks` was not passed to the payload;
+- `#lock_series` (PoC): logger/instrumenter errors broke the series call (the locks were kept till their ttl);
+- `#locks_info`: the write lock info had no `"lock_key"` field (unlike `#lock_info`);
+- the default log/instrumentation samplers were off by one percent (`0%` sampled ~1% of the cases);
+- swarm: frozen `swarm.*.redis_config` hashes failed the swarm main loops with `FrozenError`;
+- RBS: the missing `Client#current_acq_id` alias and the wrong `Client#queues_info` return type;
+- README/YARD descriptions that did not match the code (config key names, `#lock` statuses, `#lock_info` fields, results of
+  `#unlock`, `#clear_dead_requests` and `#extend_lock_ttl`);
+
 ## [1.20.0] - 2026-10-12
 ### Added
-- **Lock index** (opt-in: `config['lock_index_enabled']`, `false` by default: lock-iterating operations scan the keyspace as before):
-  `rql:index:locks` (`ZSET`: lock name => the upper bound of the lifetime of all lock keys in client time, ms); with the enabled
-  lock index all lock-iterating operations find locks without the full keyspace `SCAN` (see the "Lock Index" README section):
-  - the client-wide mode (not a per-call option): the lock acquirement maintains the lock index and lock-iterating operations
-    read it only when it is enabled; use the same mode on all processes that share the Redis database (enable it everywhere,
-    then invoke `#reindex_locks` once); the swarm reads the mode when it is started;
-  - maintained by the lock acquirement itself without new Redis round trips: each lock request adds the lock name (`ZADD GT`
-    with the queue ttl), sets the request queue TTL and drops the expired lock names (`ZREMRANGEBYSCORE`) in the queueing pipeline
-    (4 more commands per attempt), each lock obtaining (write and read) adds the lock name with the lock ttl in the same
-    transaction (1 more command), each extension (`#extend_lock_ttl`, `:extendable_work_through` reentrant locks) increases
-    the score by the extension (`ZADD XX INCR`; `#extend_lock_ttl` of write locks sends `EVAL` and the index update in one
-    transaction);
-  - `#unlock` and `#clear_locks` drop the lock names from the index in the same transaction with the lock keys;
-  - lock request queues have TTL: the queue lives as long as its latest lock request (`PEXPIRE NX` + `GT` with the queue ttl on
-    each lock request), queues of dead acquirers expire by themselves;
-  - lock-iterating operations find locks and lock queues via one `ZSCAN` pass over the lock names (lock keys are derived from
-    the lock names): the cost depends on the number of locks only, keys of other applications are never visited; locks without
-    the lock index entry (older RQL versions, the disabled lock index) are not found until `#reindex_locks`:
-    - swarm (`#flush_zombies`, the zombie flusher, `#zombie_locks`/`#zombie_acquirers`/`#zombies_info`): `zombie_lock_scan_size` is
-      the `ZSCAN` count and the batch size of locks, `zombie_queue_scan_size` - the batch size of lock queues (both processed during
-      the same pass); `#flush_zombies` drops the expired lock names from the index;
-    - `#locks`/`#locks_info`, `#queues`/`#queues_info`, `#keys`: `scan_size` is the `ZSCAN` count and the batch size of locks;
-      `#keys` returns the existing keys of the lock key families of the indexed locks (other `rql:lock*` keys are not listed);
-    - `#clear_locks`: the keys of each batch of locks are deleted with one `DEL` in one transaction with the removal of their lock
-      names from the lock index; `batch_size` is the number of locks;
-    - `#clear_locks_of`/`#clear_current_locks`: `clear_locks_of__lock_scan_size` is the `ZSCAN` count and the batch size of locks,
-      `clear_locks_of__queue_scan_size` - the number of lock queues processed in one round trip;
-    - `#clear_dead_requests`: `scan_size` is the `ZSCAN` count and the number of locks (both lock queues of each lock) processed in
-      one round trip; the expired lock names are dropped from the index;
-  - `config['lock_index_grace_period']` (`60_000` ms by default) and `lock_index_grace_period:` option of `#lock`/`#lock!`/
-    `#lock_series`/`#lock_series!`: the lock name stays in the index for this period after the expiration of all its keys
-    (the client clock skew and network latency tolerance);
-- `#reindex_locks`: adds the lock keys without the lock index entry (keys of older RQL versions and keys created with the disabled
-  lock index) to the lock index (one `SCAN` pass, lock queues without TTL get the queue ttl); **invoke it once after the lock index
-  is enabled on all your processes**;
-### Changed
-- `#flush_zombies` (and the zombie flusher of the swarm): zombie lock requests are dropped with one `ZREM` per lock queue
-  (previously one `ZREM` per zombie acquirer and lock queue);
-- `#queue_info` / `#queues_info`: lock queues are read without `EXISTS` checks (Redis does not keep empty sorted sets);
-- Lock acquirement attempt: read lock requests do not fetch the longest read lock (it is used by write lock requests only),
-  write lock requests do not build the read lock data key, disabled try-lock logs get a shared frozen hash instead of a new one;
-- Lock acquirement attempt: the lock request queueing (`ZADD NX`, expired requests pruning, queue heads) is one pipelined
-  round trip instead of three; with `:wait_for_lock`/`:dead_locking` conflict strategies (without `fail_fast`) it is sent
-  in the lock state round trip: `#lock` with a block takes 4 Redis round trips instead of 7, a failed attempt - 3 instead of 6;
-- SCAN-based operations (`#clear_locks`, `#clear_locks_of`/`#clear_current_locks`, `#clear_dead_requests`, `#locks`/`#locks_info`,
-  `#queues`/`#queues_info`, `#flush_zombies`, `#zombie_locks`/`#zombie_acquirers`/`#zombies_info`) make one `SCAN` pass instead
-  of 2-5 passes (one per key family) and send per-key commands in pipelined batches instead of one round trip per key:
-  - `#clear_locks` deletes the found keys during the scan with one `DEL` per batch (previously all keys were expired at the end,
-    lock queues first);
-  - `#clear_locks_of`/`#clear_current_locks` (`clear_locks_of__queue_scan_size`) and `#flush_zombies` (`zombie_queue_scan_size`):
-    the queue scan size is the number of lock queues processed in one round trip (queues are found by the same pass as locks);
-  - `#zombie_locks`/`#zombie_acquirers`/`#zombies_info` do not scan the keyspace when there are no zombie hosts;
-- Read lock data (`rql:lock_reader:<lock_name>:<acquirer_id>`) does not store `acq_id`/`hst_id` (both are derived from the acquirer id):
-  ~40% less memory per read lock (`MEMORY USAGE` 280 -> 168 bytes without `:meta`); `#lock_info`/`#locks_info` report them as before
-  (the first fields of each reader; read lock data of older versions is supported);
-- `#unlock`: one Redis round trip when there are no read locks (the readers registry is read in the release transaction;
-  the read lock data is dropped with one more `DEL` only when read locks existed);
-- `#lock_series` (PoC): write locks of the series are released (compare-and-delete) in one transaction for the whole series
-  (three round trips per series instead of three round trips per lock);
-- `#flush_zombies` (and the zombie flusher of the swarm): requests of zombie hosts are dropped from the lock queues by the host
-  of the request (derived from its acquirer id): requests of dead hosts that hold no locks are dropped too (previously they stayed
-  until the queue ttl) and their acquirers are reported in `deleted_zombie_acquirers`;
-- Lock acquirement: retries and `fail_fast` attempts pre-check the lock state without `WATCH` (one round trip): a retry that can not
-  obtain the lock takes 1 Redis round trip instead of 3 and a `fail_fast` attempt on an obtained lock - 1 instead of 3 (an attempt
-  that can obtain the lock continues with `WATCH`/`MULTI`: one more round trip); mutual exclusion still relies on `WATCH`/`MULTI` only;
+- *Brand New Feature*: **Lock Index** (opt-in: `config['lock_index_enabled']`, `false` by default): lock-iterating operations
+  (`#locks`, `#queues`, `#keys`, `#clear_*`, the swarm) find locks through the `rql:index:locks` index instead of the keyspace
+  `SCAN` (see README "Lock Index"):
+  - a client-wide mode: use the same mode on all processes that share the Redis database;
+  - `config['lock_index_grace_period']` and the `lock_index_grace_period:` lock option (`60_000` ms by default): the clock
+    skew tolerance of the index;
+  - lock request queues have TTL in the enabled mode (queues of dead acquirers expire by themselves);
+  - `#reindex_locks`: adds the existing lock keys to the lock index (keys of older versions and of the disabled lock index
+    are not found until then); **invoke it once after the lock index is enabled on all your processes**;
+### Changed
+- fewer Redis round trips of the lock acquirement: `#lock` with a block takes 4 instead of 7, a failed attempt - 3 instead
+  of 6, a failed retry or a `fail_fast` attempt on an obtained lock - 1 instead of 3;
+- `#unlock` (without read locks) and the `#lock_series` release take fewer round trips;
+- SCAN-based operations make one keyspace pass with pipelined batches instead of a pass per key family and a round trip per key;
+- `clear_locks_of__queue_scan_size` and `zombie_queue_scan_size` are the number of lock queues processed in one round trip;
+- read lock data takes ~40% less memory (read locks of older versions are still supported);
+- `#flush_zombies` (and the zombie flusher): lock requests of zombie hosts without locks are dropped too and reported in
+  `deleted_zombie_acquirers`;
 
 ## [1.19.0] - 2026-10-11
 ### Added
-- `#unlock_read` (aka `#release_read_lock`): an ability to unlock the read lock of any acquirer
-  - `acquirer_id:` option (`nil` by default: the current acquirer) to release the read lock of a different acquirer
-    (`identity:` is ignored when `acquirer_id:` is passed: the acquirer id already contains its own identity);
+- `#unlock_read` (aka `#release_read_lock`): the `acquirer_id:` option releases the read lock of another acquirer
+  (`nil` by default: the current acquirer);
 
 ## [1.18.0] - 2026-10-11
 ### Added
-- Brand new feature - **Read/Write locks**: `read_write_mode:` attribute of `#lock`/`#lock!`/`#lock_series`/`#lock_series!` (`:write` by default):
-  - `:write` - exclusive lock (the classic RQL lock): waits for the write lock and for all read locks;
-  - `:read` - shared lock: waits for the write lock only (read locks of different acquirers work in parallel);
-  - `:queued` access strategy orders read and write lock requests in FIFO between modes (writers are not starved by readers);
-  - `:random` access strategy ignores lock queues (a continuous flow of readers can starve writers);
-  - read locks are stored in `rql:lock_readers:<lock_name>` (`ZSET`: acquirer id => expiration time in Redis time),
-    read lock requests - in `rql:lock_read_queue:<lock_name>`, read lock data - in `rql:lock_reader:<lock_name>:<acquirer_id>`
-    (the same structure as the write lock: acquirer, host, timestamp, ttl, `:meta`, reentrant lock data);
-    write locks and write lock requests use the classic keys;
-  - mutual exclusion is based on optimistic transactions (`WATCH`/`MULTI`, no Lua): readers watch the write lock key,
-    writers watch the write lock key and the read locks key (readers never invalidate transactions of each other);
-  - reentrant locks: read lock request under the obtained lock works as a reentrant lock of the obtained lock;
-    read-to-write lock upgrade fails with `RedisQueuedLocks::ConflictLockObtainError` (`:conflict_lock_upgrade`)
-    for `:work_through`/`:extendable_work_through` conflict strategies;
-  - `#unlock`, `#clear_locks`, `#clear_locks_of`, `#clear_current_locks`, `#clear_dead_requests`, `#flush_zombies`,
-    `#zombie_locks`, `#zombie_acquirers`, `#zombies_info`, `#locked?`, `#queued?`, `#lock_info`, `#queue_info`,
-    `#locks`, `#locks_info`, `#queues`, `#queues_info` support read locks and read lock requests;
-  - logs: `rw_mode` in the lock logs and in the lock series logs (`start_lock_series_obtaining`, `lock_series_obtained`,
-    `expire_lock_series`: the mode of the series); new try-lock log events: `exit__write_request_ahead`, `exit__read_request_ahead`,
-    `exit__read_lock_still_obtained`, `single_process_lock_conflict__lock_upgrade`;
-  - instrumentation: `rw_mode` in `lock_obtained`, `reentrant_lock_obtained`, `extendable_reentrant_lock_obtained`,
-    `lock_hold_and_release`, `reentrant_lock_hold_completes` payloads and in the lock series payloads
-    (`lock_series_obtained`, `lock_series_hold_and_release`: the mode of the series);
-  - `:meta` for read locks (stored in the read lock data of each reader, returned by `#lock_info`/`#locks_info`);
-  - `#lock_series` with `read_write_mode: :read` (PoC): a series of read locks; only read locks obtained by the series
-    are released (reentrant read locks of the outer logic are kept);
-  - `#unlock_read` (aka `#release_read_lock`): releases the read lock of the current acquirer only
-    (new instrumentation event: `redis_queued_locks.explicit_read_lock_release`);
-  - `#extend_lock_ttl`: `read_write_mode:` (`:write` by default) and `identity:` options; `:read` mode extends the read lock
-    of the current acquirer only (an expired read lock or a read lock replaced by a writer is not extended);
-  - `#extend_lock_ttl`: `all_read_locks:` option (`false` by default, `:read` mode only, ignored in `:write` mode):
-    extends all live read locks of the lock (expired read locks are not revived);
+- *Brand New Feature*: **Read/Write locks**: `read_write_mode:` of `#lock`/`#lock!`/`#lock_series`/`#lock_series!`
+  (`:write` by default; `:read` is a shared lock that waits for the write lock only; see README "Read/Write Locks"):
+  - `:queued` orders read and write lock requests in FIFO between modes (`:random` can starve writers);
+  - reentrant read locks; a read-to-write upgrade fails with `:conflict_lock_upgrade` for `:work_through` /
+    `:extendable_work_through`;
+  - all lock operations (releases, cleanups, zombies, lock info, `#lock_series`) and `:meta` support read locks;
+  - `#unlock_read` (aka `#release_read_lock`) with the `redis_queued_locks.explicit_read_lock_release` event;
+  - `#extend_lock_ttl`: `read_write_mode:`, `identity:` and `all_read_locks:` options;
+  - `rw_mode` in the lock logs and instrumentation payloads, `#lock_info`/`#locks_info` and `#queue_info`/`#queues_info`;
+    new try-lock logs (see README `## Logging`);
+  - `:meta`: `"rw_mode"` is a reserved lock data key;
   - RBS: `read_write_mode` is typed as `:read | :write`;
-  - `#queue_info` / `#queues_info`: each lock request has `"rw_mode"` (`"write"` / `"read"`);
-  - `#lock_info` / `#locks_info`: write lock info has `"rw_mode" => "write"` (read locks info - `"rw_mode" => "read"`);
-  - `:meta`: `"rw_mode"` is a reserved lock data key (`RedisQueuedLocks::ArgumentError`), for write and read locks and lock series;
-  - **all processes should use the RQL version with read/write locks** before read locks are used
-    (write locks of older RQL versions do not check read locks);
-### Changed
-- `lock_series_obtained` instrumentation event (`#lock_series`, PoC): `:ts` is an epoch timestamp (`Float`)
-  like in all other instrumentation events (previously a `Time#to_s` string);
-- **Breaking**: `#extend_lock_ttl` success result is `{ ok: true, result: { extended_locks_count: Integer } }`
-  instead of `{ ok: true, result: :ttl_extended }` (the number of locks whose TTL is extended: `1` for the write lock
-  and for the own read lock, the number of extended read locks for `all_read_locks: true`);
-  the failure result is unchanged (`{ ok: false, result: :async_expire_or_no_lock }`);
-- Lock acquirement attempt: the lock state is fetched in one pipelined round trip; lock data for
-  `exit__no_first`/`exit__lock_still_obtained` try-lock logs is extracted only when these logs are enabled
-  (previously `HGETALL` was called on every unsuccessful attempt);
+  - **all processes should use the RQL version with read/write locks** before read locks are used (write locks of older
+    versions do not check read locks);
+### Changed
+- [**Breaking**] `#extend_lock_ttl` success result is `{ ok: true, result: { extended_locks_count: Integer } }` instead of
+  `{ ok: true, result: :ttl_extended }`;
+- `lock_series_obtained` instrumentation event (`#lock_series`, PoC): `:ts` is an epoch `Float` (was a `Time#to_s` string);
+- a lock acquirement attempt makes fewer Redis calls;
 ### Fixed
-- `dequeue_from_lock_queue` log: unclosed quote in the `acs_strat` value;
-- `extendable_reentrant_lock_obtained` log: the host identifier is logged as `hst_id` (was `host_id`), like in all other logs;
-- `start_lock_series_obtaining` log: missing space between the `lock_keys` and `queue_ttl` values;
-- `lock_series` PoC:
-  - locks obtained by the failed series are released when the series fails without an exception
-    (`raise_errors: false`); previously they lived till their TTL;
-  - reentrant locks of the series (already obtained by the outer logic of the same acquirer) are not released
-    by the series anymore (previously the outer logic continued to work without its lock);
-  - the series releases only write locks that are still owned by the current acquirer (compare-and-delete):
-    a lock expired during the block and obtained by another acquirer is not deleted anymore;
+- logs: an unclosed quote in `dequeue_from_lock_queue`, a missing space in `start_lock_series_obtaining`, `host_id` instead of
+  `hst_id` in `extendable_reentrant_lock_obtained`;
+- `#lock_series` (PoC):
+  - a series failed without an exception (`raise_errors: false`) kept its obtained locks till their TTL;
+  - the series released the reentrant locks of the outer logic of the same acquirer;
+  - the series could delete a lock that expired during the block and was obtained by another acquirer;
 
 ## [1.17.0] - 2026-10-04
 ### Changed