redis_queued_locks 1.19.0 → 1.20.0

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

@@ -0,0 +1,372 @@
+---
+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.
+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
+`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.
+
+- Report defects, with a concrete failure scenario and the rule they break. Every rule-based finding cites its
+  source (`acquirer.md#12` = rule 12 of the "Claude rules" list in `.claude/rules/acquirer.md`, `overview "Lock index"`).
+- The review is read-only: don't edit, stage or commit anything. After a review on request, offer to fix the
+  findings; the automatic pre-commit run acts on them itself (see "When to run").
+- Write the report from the template that matches the Claude Code `language` setting, English when that language
+  has no template (§7); code identifiers, rule names and quotes stay as they are.
+
+## When to run
+
+- On request: the user asks for a review (any scope of §1).
+- Automatically, as the pre-commit review (`git.md#7`): when a task in this repository (a feature, a fix, a prompt,
+  a docs or `.claude` change) is done and committable, at the moment the commit question would be asked or a commit
+  authorized in advance would be made (`git.md#8`). Never earlier: not during the implementation, not after
+  intermediate edits, not for incomplete or red states (`git.md#9`), not for an explicit commit request.
+  - 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).
+  - 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`).
+  - The report is followed by the commit question (`git.md#7`) with the verdict and the remaining Minor/Nit findings.
+
+## 1. Scope
+
+| Argument | Diff to review |
+|---|---|
+| `uncommitted` | the changes of the current step: `git diff HEAD` (staged + unstaged) plus untracked files (`git status --porcelain`); the scope of the automatic pre-commit run |
+| none | the branch against `master`: `git merge-base master HEAD`, then `git diff <base>` (committed + staged + unstaged) plus untracked files (`git status --porcelain`). On `master` with a clean tree there is nothing to review: ask for a target |
+| `base..head` / `<commit>` | `git diff base..head` / `git show <commit>` |
+| `staged` | `git diff --cached` |
+| `pr <N>` | `gh pr diff <N>` when `gh` is installed, otherwise `git fetch origin pull/<N>/head` + `git diff master...FETCH_HEAD` (no local branch) |
+| `<paths...>` | the whole files: report real defects and rule violations, but pre-existing known debt (§5) is not a finding |
+
+- Start with `git diff --name-status` and `git diff --stat`, record the base sha.
+- Environment artifacts are never part of a change (`git.md#10`): `rbs_collection.lock.yaml` rewritten by
+  `rbs collection install`, `coverage/`, `.gem_rbs_collection/`, `.claude/settings.local.json`, `.DS_Store`.
+  Flag them only when they are committed or about to be.
+- Big diffs: learn the intent first (commit subjects `git log --format=%s <base>..HEAD`, the CHANGELOG
+  `[Unreleased]` and overview hunks), then review in dependency order: `resource.rb`/`config.rb` →
+  `acquire_lock/*` → other `acquirer/*` → `client.rb` → `swarm/*` → `sig/` → docs; specs last, for coverage only.
+
+## 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):
+
+| Changed path | Rule files |
+|---|---|
+| `lib/**` | `logic.md`, `type-checking.md` |
+| `lib/redis_queued_locks/acquirer/**` | + `acquirer.md`, `arguments.md`, `visitors.md` |
+| `client.rb`, `config.rb`, `swarm.rb` | + `arguments.md` |
+| `swarm/**`, `sig/redis_queued_locks/swarm/**` | + `swarm.md` |
+| `logging/**`, `instrument/**` | + `visitors.md` |
+| `sig/**`, `Steepfile`, `rbs_collection.yaml` | `type-checking.md` |
+| `spec/**` | `tests.md` (coverage expectations only, see §3) |
+| commits / messages | `git.md` |
+
+- Read every changed method in full, its callers, its RBS signature and every copy of duplicated logic. Copies
+  that must change together:
+  - write lock info formatting `LockInfo.lock_info` ↔ `Locks.extract_locks_info`; reader formatting
+    `LockInfo.read_lock_info` ↔ `Locks.read_lock_info`; request formatting `QueueInfo.queue_info` ↔
+    `Queues.extract_queues_info`;
+  - `each_lock_name_batch` in `Locks`, `Queues`, `Keys`, `ReleaseAllLocks`, `ReleaseLocksOf`,
+    `ClearDeadRequests` (inline iteration in `FlushZombies.flush_lock_index_zombies` and
+    `ZombieInfo.each_lock_index_zombie_lock`); `ZombieInfo` lookups mirror `FlushZombies`;
+  - `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`;
+  - 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.
+- 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.
+
+## 3. Spec files are exempt (until the suite rework)
+
+`spec/**/*_spec.rb` are not ideal and are going to be rewritten entirely (header `NOTE` of
+`spec/redis_queued_locks_spec.rb`, overview "Conventions", rspec-retry as temporary debt). Until then any coding
+principle may be broken there. Never report the way specs are written: duplication, long or nested examples, `sleep` waits,
+anonymous fakes, magic numbers, naming, structure, `it`/`specify`, rubocop directives, thread handling,
+cleanup style, retry reliance, file size, the `tests.md` rules on writing specs and its recommendations.
+
+Still in scope (the exemption covers how specs are written, not whether the library is tested):
+1. Coverage of the changed library behavior (finding against the `lib/` change, category `test-coverage`):
+   new behavior without an example; RW changes without both modes (`tests.md#13`); lock-iterating changes without
+   the small-batch examples of both lookups and the recorded-command checks (`acquirer.md#7`); new lock index
+   writes without `describe 'lock index'` examples (`acquirer.md#16`); a changed pipeline layout without an updated
+   `lock state pipeline layout` spec (`acquirer.md#15`); a touched obtaining transaction that the spec
+   `the lock obtaining transaction indexes the lock` no longer exercises (it drops the index entry right before the
+   obtaining `MULTI`); a new log/instrumentation event without a fake logger/notifier assertion (`visitors.md#11`).
+2. A changed spec that asserts behavior contradicting the overview/rules, or that can't fail for the behavior
+   it claims to check (vacuous expectation, expectation never reached).
+
+`spec/spec_helper.rb` and `spec/setup_simplecov.rb` are support files: review them for correctness only (the
+`around` hook that switches `config['lock_index_enabled']` and restores the library default).
+
+## 4. Checklist
+
+### A. Lock safety and Redis correctness
+- Mutual exclusion only from the lock state checked under `WATCH`/`MULTI` (`logic.md#6`, `#14`); Lua only for the
+  existing write TTL extension/decrease, no new Lua in the RW acquisition path unless the user asked. No
+  check-then-set in Ruby without a transaction; queues, client clocks, the lock index and the pre-check never
+  decide mutual exclusion (the pre-check never obtains the lock).
+- Asymmetric WATCH (`acquirer.md#12`): writers watch `[lock_key, lock_readers_key]`, readers `[lock_key]` only.
+  No write to a watched key outside `MULTI` after `WATCH` (aborts the own `EXEC`); never merge `WATCH` into a
+  pipeline (unsafe on reconnect).
+- Lock state: write needs no write lock and no live readers; read needs no write lock; same-acquirer cases go
+  through `conflict_strategy`; read→write upgrade never works through (`:conflict_lock_upgrade`, waits with
+  `:wait_for_lock`).
+- Time: reader liveness and expirations in Redis time (`TIME` → `Resource.redis_time_ms`, `PEXPIRE`); client
+  `Time.now.to_f` only for queue positions, `ts` fields, zombie probes; lock index scores in
+  `Resource.lock_index_time` (epoch ms) + grace. Readers are live only while `score > now`: never decide by
+  `ZCARD`/`EXISTS` alone.
+- TTLs: max-TTL keys (registry, reader data, queues) get the `PEXPIRE NX` + `PEXPIRE GT` pair (`GT` alone sets
+  nothing on a key without TTL); `PTTL` sentinels handled (`-2` missing, `-1` → `Float::INFINITY` / `'+inf'`);
+  units right (ttl ms, `queue_ttl` s → `(queue_ttl * 1_000).ceil`, `zombie_ttl` ms → `/ 1_000.0`), integers for
+  `PEXPIRE`.
+- Replies read by position (`acquirer.md#15`): `NOTE: (pipeline layout)` next to the commands, conditional
+  commands form a tail after the unconditional ones and are read under the same condition, position constants
+  (`LOCK_STATE_*`, `QUEUE_HEAD_REPLY`, `KEY_STATE_REPLIES`, `LOCK_STATE_REPLIES`) and the layout spec updated;
+  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:)`).
+- 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`)
+- 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.
+- 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,
+  `acquirer.md#11`); `rw_mode` stays a reserved `meta` key.
+- Backward compatibility: data written by older versions (readers with `acq_id`/`hst_id`, names without index
+  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")
+- 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`.
+- Superset invariant: every key-creating command is followed by `ZADD <index> GT <now + lifetime + grace> <name>`
+  in the same pipeline/transaction, after the key command; the obtaining `MULTI` indexes the lock itself; every
+  extension is followed by `ZADD XX INCR`; scores never decrease; names are removed only in the same `MULTI`
+  that deletes all their keys (`ReleaseLocksOf`, `YieldExpire` releases and `FlushZombies` never remove names).
+- Lock index commands are conditional tails: reply positions never depend on the mode.
+- A new key family: distinct prefix `rql:lock_<kind>:<name>` (never a suffix of the name), bounded TTL in the
+  enabled mode, covered by the index score, `Resource.lock_key_family`/`lock_name_from_key`, both lookups and
+  `ReindexLocks`.
+- `lock_index_enabled` is client-wide (`arguments.md#9`): read from `config` inside `Client`/`Swarm` and forwarded,
+  never a keyword of a public method; the flusher Ractor gets a copy. `lock_index_grace_period` is forwarded by
+  `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`)
+- 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`,
+  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
+  (`lock_index_enabled ? index_x : scan_x` or one `if`/`else` with `(lock index)`/`(keyspace)` step comments) and
+  keeps the shared processing in one copy.
+- No `EXISTS` next to `ZRANGE`/`HGETALL`: Redis never keeps empty sorted sets/hashes.
+- Hot path (`AcquireLock`, `TryToLock`, `YieldExpire`, `DequeueFromLockQueue`, visitor call sites): no wrapper
+  objects, hash merging, splats to build arguments, closures for argument plumbing, new `{}` per attempt (use
+  `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
+- `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
+  (`arguments.md#1`, `#3`); a new public option goes to every `Client` variant with a `config` default
+  (`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,
+  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`;
+  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
+  helpers, `require_relative` in `acquirer.rb`, thin `Client` method, RBS, spec, README/CHANGELOG
+  (`acquirer.md#1`). Mutating operations follow the two-layer pattern (timing wrapper + private `fully_*`,
+  `acquirer.md#2`).
+- Results: `{ ok:, result: }` only at the public boundary (`Client`, `Acquirer::*`, `Swarm` facade actions) with
+  Symbol statuses and abbreviated Symbol keys (`rel_*`, `*_cnt`, `*_time`); info queries return a String-keyed
+  Hash/Set or `nil`; swarm element internals return bare scalars (`swarm.md#15`). Raise only in `x!` methods, the
+  `raise_errors` path of `AcquireLock` and on invalid arguments (`RedisQueuedLocks::ArgumentError`), with the lock
+  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`.
+- `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`)
+- 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`,
+  logger, Redis client; inside only shareable constants and module functions (`#4`, `#5`).
+- Ports (`#13`): results port created in the main Ractor, commands port inside the element Ractor, `monitor`
+  registered before waiting, one reply per command, Symbol messages reserved for death notices; no
+  `Ractor.receive`/`Ractor#send`/default port; names end in `_port`, block params `r_res_p`/`r_com_p`.
+- Threads: kill + join inside the Ractor (`#14`), `abort_on_exception = false` for main loops, no retry loops in
+  elements (`#8`); state changes and request/reply pairs inside `sync.synchronize` (`#6`); the supervisor is
+  stopped before elements are killed or re-created (`#9`).
+- 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`).
+- 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
+  `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`.
+- 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` /
+  `### Instrumentation Events` and CHANGELOG (`#14`).
+
+### H. 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
+  swarm internals, `Hash[String, ...]` instead of String-keyed records (they crash Steep).
+- `# steep:ignore` only where Steep reports a diagnostic (strict mode fails on redundant ignores); prefer
+  `# @type var x: T` / `#: T` and tuple annotations of pipeline results; a needed ignore without an honest
+  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
+- `# 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`).
+- 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|`
+  for multi-command work, `multi do |transact|`, `pipelined do |pipeline|`, named reply variables (`hget_cmd_res`,
+  `lock_state`), Lua as a frozen `<<~LUA_SCRIPT.strip.tr("\n", '').freeze` constant (`acquirer.md#5`, `#6`).
+- Normalization with `Float(...)`/`Integer(...)` inside `tap do |lock_data|`, optional fields guarded with
+  `if lock_data['x']` (`acquirer.md#11`).
+- Idioms: `x == nil`/`x != nil` or truthiness (not `.nil?`); `raise(Klass, "message")` with `\` continuations;
+  subject-less `case` with `start_with?` instead of regexps on hot paths; shorthand `key:` forwarding;
+  `clock_gettime` (µs) for durations reported as `((finish - start) / 1_000.0).ceil(2)` ms, `Time.now.to_f` only for
+  `at:`/`ts`; names `rconn`, `transact`, `pipeline`, `*_key`, `*_queue`, `acquirer_id`/`host_id` (`acq_id`/`hst_id`
+  in data, logs and payloads), private `fully_*`, `scan_*`/`index_*` lookups, `swarmed__*` predicates.
+- 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.
+
+### J. 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.
+- Commits under review (`git.md`): subject only `[<scope>] <summary>`, lowercase, imperative, no trailing period,
+  no body except the attribution trailer, never on `master`.
+
+## 5. Do not report
+
+- Settled design (overview, `acquirer.md`, `swarm.md`): long explicit parameter lists and disabled
+  `Metrics/ParameterLists`; logic duplicated between operation modules (report only diverged copies);
+  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`.
+- 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.
+- "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
+  "outside the diff" section.
+- Anything in `*_spec.rb` except §3.
+
+## 6. Verify every finding
+
+- 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.
+- 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:
+  - added key literals and scans (outside `resource.rb` every `'rql:` literal is a finding):
+    `git diff <base> -U0 -- lib | grep '^+' | grep -v '^+\s*#' | grep -n "'rql:\|\"rql:\|'KEYS'\|'SCAN'\|\.scan(\|\.zscan("`;
+  - `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);
+  - `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
+  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.
+
+## 7. Report
+
+### Template language
+The report template is chosen by the Claude Code `language` setting:
+1. Take the effective value: the first settings file that defines `language`, in precedence order (run from the
+   repository root; Ruby is always available here, `jq` may be not):
+   ```sh
+   for f in "/Library/Application Support/ClaudeCode/managed-settings.json" /etc/claude-code/managed-settings.json \
+            .claude/settings.local.json .claude/settings.json ~/.claude/settings.json; do
+     [ -f "$f" ] && v=$(ruby -rjson -e 'print JSON.parse(File.read(ARGV[0]))["language"].to_s' "$f" 2>/dev/null) \
+       && [ -n "$v" ] && { echo "$v"; break; }
+   done
+   ```
+   Settings passed with `--settings` override these files; the session's response-language instruction (it comes
+   from the same setting) then shows the effective value.
+2. Map the value case-insensitively to a template in `.claude/skills/rql-code-review/templates/`:
+
+   | `language` value | Template |
+   |---|---|
+   | Russian: `russian`, `русский`, `ru`, `ru-RU`, `ru_RU`, ... | `report.ru.md` |
+   | English (`english`, `en`, `en-US`, ...), any language without a template (`japanese`, `de`, ...), no value | `report.en.md` |
+
+3. Read the chosen template and fill it in. The whole report (headings, labels, verdict, findings) is written in the
+   template language; code identifiers, rule names, quotes and the `CONFIRMED`/`PLAUSIBLE` markers stay as they
+   are. Text outside the report (the offer to fix) follows the session language.
+
+Both templates have the same structure: change them together. A new language = a new `report.<code>.md` with the
+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.
+- 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
+  checks sections list what was checked.

data/.claude/skills/rql-code-review/templates/report.en.md

@@ -0,0 +1,31 @@
+## Review: <scope> (<N> files, base <sha>)
+**Verdict:** <blockers found | mergeable after fixes | no findings> — <one sentence why>
+
+### Blockers
+1. `<path>:<line>` — <the defect in one sentence>. [CONFIRMED | PLAUSIBLE: <assumption>]
+   Scenario: <input / state / interleaving → wrong result>.
+   Rule: <`acquirer.md#16` | overview "Lock index">.
+   Fix: <what to do>.
+
+### Major
+<findings in the same format>
+
+### Minor
+<findings in the same format>
+
+### Nits
+<findings in the same format>
+
+### Docs and types sync
+- RBS: <ok | what is missing>
+- overview and rules: <ok | what is missing>
+- README and CHANGELOG: <ok | what is missing>
+- YARD (`@since`/`@version`): <ok | what is missing>
+
+### Checks
+- rubocop: <result>
+- steep: <result>
+- rspec: <not run (reason) | result>
+
+### Outside the diff and suggestions
+- <a severe problem outside the diff or an optional suggestion>

data/.claude/skills/rql-code-review/templates/report.ru.md

@@ -0,0 +1,31 @@
+## Ревью: <scope> (<N> файлов, base <sha>)
+**Вердикт:** <есть блокеры | можно мержить после правок | замечаний нет> — <одна фраза почему>
+
+### Блокеры
+1. `<path>:<line>` — <дефект одним предложением>. [CONFIRMED | PLAUSIBLE: <допущение>]
+   Сценарий: <входные данные / состояние / интерливинг → неверный результат>.
+   Правило: <`acquirer.md#16` | overview "Lock index">.
+   Исправление: <что сделать>.
+
+### Важные
+<находки в том же формате>
+
+### Мелкие
+<находки в том же формате>
+
+### Придирки
+<находки в том же формате>
+
+### Синхронизация документации и типов
+- RBS: <ок | чего не хватает>
+- overview и rules: <ок | чего не хватает>
+- README и CHANGELOG: <ок | чего не хватает>
+- YARD (`@since`/`@version`): <ок | чего не хватает>
+
+### Проверки
+- rubocop: <результат>
+- steep: <результат>
+- rspec: <не запускался (причина) | результат>
+
+### Вне диффа и предложения
+- <серьёзная проблема вне диффа или необязательное предложение>

data/CHANGELOG.md

@@ -1,5 +1,73 @@
 ## [Unreleased]
 
+## [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;
+
 ## [1.19.0] - 2026-10-11
 ### Added
 - `#unlock_read` (aka `#release_read_lock`): an ability to unlock the read lock of any acquirer

data/CLAUDE.md

@@ -14,6 +14,8 @@ Full details (config keys, key layout, events, errors, stack, CI): `.claude/proj
 - `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.
 - 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. 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".
 - 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.
@@ -30,7 +32,7 @@ Detailed, path-scoped rules in `.claude/rules/`: `logic.md` (lib, general), `acq
 - 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`.
 - New option: `setting` (+ `validate`) in `config.rb`.
 - 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) ask before committing, with the proposed subject and a recap of the changes; an explicit "commit" request needs no extra question; never on `master`, never push.
+- 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.
 - Before implementing, read the relevant sections of `.claude/project-overview.md` (key layout, lock flow, "Read/Write locks", events) and keep their invariants. In the same change, update the overview and the affected `.claude/rules/*.md` for every new/changed key, option, result shape, event, algorithm step or limitation (and README/CHANGELOG `[Unreleased]` for user-visible behavior). New or changed log keys / instrumentation payload keys (visitors or inline `notify`) also go to README `## Logging` / `### Instrumentation Events` (see `visitors.md`).
-- Lock-touching code is read/write-aware: any operation over locks, queues, zombies or lock info must cover the read family (`rql:lock_readers:*`, `rql:lock_read_queue:*`, `rql:lock_reader:*`) next to `rql:lock:*`/`rql:lock_queue:*`. Mutual exclusion comes only from WATCH/MULTI on lock state (no Lua in the RW acquisition path unless asked); queues never guarantee safety.
+- Lock-touching code is read/write-aware and index-aware: any operation over locks, queues, zombies or lock info must cover the read family (`rql:lock_readers:*`, `rql:lock_read_queue:*`, `rql:lock_reader:*`) next to `rql:lock:*`/`rql:lock_queue:*`, and any new key-creating/extending command must keep the lock index a superset of the existing locks (enabled mode); a new lock-iterating operation implements both lookups (keyspace and lock index, `lock_index_enabled`). Mutual exclusion comes only from WATCH/MULTI on lock state (no Lua in the RW acquisition path unless asked); queues never guarantee safety.
 - Known debt: rspec-retry, disabled coverage minimum, runtime type-check CI uses `--failure-exit-code=0`.