familia 2.7.0 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b0138946cb9d48258b9f43b8a8a81aa895bfded213543feee354b3d383dd98a
-  data.tar.gz: bd5b6ee397c2ef19cef85fe7638ead34b5ed40a81c8362f539ed757d0d713ca2
+  metadata.gz: 42bbbbcb737ab4222505955e5b1af2ab72ed962ba80a02cf324206b4f2379b94
+  data.tar.gz: 331b1d0bb0808618a87d962e1b09af61a31d59b7b8d56b0f49513cb9f3fec63d
 SHA512:
-  metadata.gz: 8108ee045d1f4f1bdc722a1b56a6518a32edebd18ae028dfdcd793a62044cc8bea509e06d8399179c11b1eeef971dd980d1bcd18654cd3a375af99b641c514a6
-  data.tar.gz: 395bcb27503bb30734d0d6e16fa8e95b33fa072dfaca56c2b9b06d33859c4cb915f766923a492cbdaae5407e45db2c76ee074a6c6d7aac245b822332f44d082c
+  metadata.gz: 9ff40710ce23c2f3dadbfbf68142800b8f10590c898f30f424819a4f0efea9aa545c52307c487c6fd96bf0c0f95f7504e5614056a30039f75f9db84fe1fcd595
+  data.tar.gz: be6c618b3fab3eb5ac8577c8a4bd7fbbbc53ce300da750baf3f64d70807a0aeb2a3a7a7f28da91d7637ebe86d9f2ccc86b677478ed90ab3ae7878d6d8816cd09

data/.pre-commit-config.yaml

@@ -62,8 +62,6 @@ repos:
     rev: v1.32.2
     hooks:
       - id: talisman-commit
-        env:
-          TALISMAN_SCAN_MODE: CI
 
   # Commit message issue tracking integration
   - repo: https://github.com/delano/add-msg-issue-prefix-hook

data/CHANGELOG.rst

@@ -7,6 +7,242 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.9.0:
+
+2.9.0 — 2026-05-17
+==================
+
+Added
+-----
+
+- Batch iteration primitives for DataTypes via ``Enumerable`` integration:
+
+  - All DataTypes (``SortedSet``, ``HashKey``, ``UnsortedSet``, ``ListKey``) now
+    ``include Enumerable``, providing ``each_slice``, ``lazy``, ``map``, ``reduce``,
+    ``find``, and other stdlib methods.
+
+  - **SortedSet#each(since:, until:)**: Cursor-based iteration with optional
+    timestamp bounds. Uses ZRANGEBYSCORE when bounds provided (inclusive),
+    ZSCAN otherwise. Accepts Time objects or numeric scores.
+
+  - **HashKey#each(matching:)**: Cursor-based iteration via HSCAN with optional
+    glob pattern filter on field names.
+
+  - **UnsortedSet#each(matching:)**: Cursor-based iteration via SSCAN with optional
+    glob pattern filter using Redis SSCAN MATCH on raw values.
+
+  - **ListKey#each(batch_size:)**: Memory-efficient LRANGE pagination for large lists.
+
+- ``DataType#each_record(batch_size:, write_size:, **filters)`` yields loaded
+  Horreum records (not raw IDs) via ``load_multi``. Ghost instances (expired keys
+  still in ``instances``) are automatically filtered. The ``write_size:`` parameter
+  controls pipelining depth (``nil`` for serial execution).
+
+- ``Familia::BatchResult`` value type for aggregating batch operation results:
+
+  - ``BatchResult.collect(enumerable, strict: false) { |record| ... }`` iterates
+    any Enumerable, tracking ``scanned``, ``modified`` (truthy returns), ``errors``
+    (array of ``{id:, error:}``), and ``duration_ms``.
+
+  - Per-record exception isolation: errors are captured and iteration continues.
+
+  - ``strict: true`` re-raises collected errors after iteration completes.
+
+Changed
+-------
+
+- Renamed batch field-update methods for clarity:
+
+  - ``batch_update`` is now ``multi_field_update``
+  - ``batch_fast_write`` is now ``multi_field_fast_write``
+
+  Old names removed without deprecation shim (breaking change).
+
+- Moved ``MultiResult`` into Familia namespace as ``Familia::MultiResult``.
+  Old top-level constant removed without backwards-compat alias (breaking change).
+
+AI Assistance
+-------------
+
+- Implementation and test coverage developed with parallel Claude Code agents:
+  one for production code (DataType iteration, BatchResult, renames), one for
+  Tryouts test suite (228 new tests across 8 files). PR #264.
+
+.. _changelog-2.8.0:
+
+2.8.0 — 2026-05-15
+==================
+
+Added
+-----
+
+- Expanded Redis 7 command coverage across all DataType classes:
+
+  - **StringKey**: ``incrbyfloat``, ``getex``, ``getdel``, ``setex``, ``psetex``,
+    ``bitcount``, ``bitpos``, ``bitfield``, plus class methods ``mget``, ``mset``,
+    ``msetnx``, ``bitop`` for multi-key and bitwise operations.
+
+  - **List**: ``trim``/``ltrim``, ``set``/``lset``, ``insert``/``linsert``,
+    ``move``/``lmove``, ``pushx``/``rpushx``, ``unshiftx``/``lpushx``.
+    Updated ``pop`` and ``shift`` to support optional count parameter for batch operations.
+
+  - **UnsortedSet**: ``intersection``/``inter``, ``union``, ``difference``/``diff``,
+    ``member_any?``/``members?``, ``scan``, ``intercard``/``intersection_cardinality``,
+    ``interstore``/``intersection_store``, ``unionstore``/``union_store``,
+    ``diffstore``/``difference_store``.
+
+  - **SortedSet**: ``popmin``, ``popmax``, ``score_count``/``zcount``, ``mscore``,
+    ``union``, ``inter``, ``rangebylex``, ``revrangebylex``, ``remrangebylex``,
+    ``lexcount``, ``randmember``, ``scan``, ``unionstore``, ``interstore``,
+    ``diff``, ``diffstore``.
+
+  - **HashKey**: ``scan``/``hscan``, ``incrbyfloat``/``incrfloat``,
+    ``strlen``/``hstrlen``, ``randfield``/``hrandfield``, plus field-level TTL
+    commands (Redis 7.4+): ``expire_fields``, ``pexpire_fields``, ``expireat_fields``,
+    ``pexpireat_fields``, ``ttl_fields``, ``pttl_fields``, ``persist_fields``,
+    ``expiretime_fields``, ``pexpiretime_fields``.
+
+- Added 158 new tests across 5 test files covering all new methods.
+
+- Instance-scoped ``audit_multi_indexes`` is now fully implemented.
+  Discovers per-scope bucket keys via SCAN, partitions them by scope
+  instance, and reports stale members, orphaned buckets, and missing
+  entries in the same shape as the class-level audit. Orphan entries
+  carry a ``:reason`` (``:scope_missing`` or ``:field_value_unheld``)
+  and a ``:scope_id``. Missing entries are detected via the indexed
+  class's ``participates_in`` relationship to the scope class; when
+  absent, the result carries ``missing_status: :not_audited``.
+  Resolves the ``:not_implemented`` follow-up from #217.
+
+- ``repair_multi_indexes!`` class method that invokes the existing
+  ``rebuild_<index_name>`` methods for both class-level (one call on
+  the indexed class) and instance-scoped (one call per scope
+  instance) multi-indexes. Indexes whose audit status is ``:ok`` are
+  skipped; rebuild methods that don't exist or scope classes
+  without an ``instances`` collection are recorded in ``:skipped``
+  with a reason.
+
+- ``housekeeping`` feature gains a class-level bulk runner,
+  ``Klass.run_chores!(chore_name:, limit:, batch_size:)``. It iterates
+  the class's ``instances`` collection in pipelined batches via
+  ``load_multi``, runs all registered chores (or one named chore)
+  against each record, and returns a stats hash:
+  ``{ model:, scanned:, chores: { name => { modified:, errors: } } }``.
+  Truthy chore returns increment ``modified``; raised exceptions are
+  isolated per-record, logged via ``Familia.warn``, and counted as
+  ``errors`` so a single failure doesn't halt the run. Lifted from the
+  shape proven out in OneTime Secret's ``HousekeepingJob``.
+
+- Trace events for connection-mode conflicts. ``Familia.trace`` now
+  emits ``CONFLICTING_CONTEXT`` when pipeline and transaction
+  contexts collide (in both ``FiberPipelineHandler``/
+  ``FiberTransactionHandler`` and the
+  ``execute_transaction``/``execute_pipeline`` entry points), and
+  ``FAST_WRITER_BLOCKED`` when a fast writer (``field!``) is called
+  inside a transaction or pipeline. These fire just before the
+  corresponding ``ConflictingContextError`` /
+  ``OperationModeError`` is raised, so operators can pinpoint where
+  blocked operations originate when ``FAMILIA_TRACE=1``.
+
+Changed
+-------
+
+- ``repair_all!`` now runs each repair stage inside its own rescue
+  boundary; a failure in one dimension no longer prevents the others
+  from running. The return hash gains ``:status`` (``:ok`` or
+  ``:partial_failure``), ``:errors`` (per-stage exception details
+  when raised), and ``:multi_indexes`` (results from the new
+  ``repair_multi_indexes!``). An opt-in ``verify: true`` kwarg
+  re-runs ``health_check`` after repair and exposes the result as
+  ``:post_audit`` / ``:verified`` so callers can confirm the run
+  actually drove the model back to a healthy state.
+
+- ``AuditReport#complete?`` is no longer false-positive due to
+  ``:not_implemented`` stubs in ``multi_indexes`` -- instance-scoped
+  indexes return ``:ok`` or ``:issues_found`` like class-level ones.
+
+- ``housekeeping`` feature: split the dual-purpose ``tidy!`` into two
+  explicit instance methods. ``do_chore!(name)`` runs a single named
+  chore and returns the block's raw return value (no longer wrapped
+  in a ``{name => result}`` hash). ``do_chores!`` runs every
+  registered chore and returns the ``{name => result}`` hash.
+  ``tidy!`` is preserved as an alias of ``do_chores!`` for backwards
+  compatibility with the 2.7.0 no-arg call site; the single-arg form
+  ``tidy!(:name)`` now raises ``ArgumentError``.
+
+- The connection handler hierarchy has been refactored from class
+  inheritance (``BaseConnectionHandler``) to module composition.
+  Handlers now ``include Familia::Connection::Handler`` and declare
+  their operation-mode capabilities with a small DSL:
+  ``supports transaction: true, pipelined: false``. The
+  ``BaseConnectionHandler`` constant is gone. This is only relevant if
+  you have custom handlers in application code — the public
+  ``allows_transaction`` / ``allows_pipelined`` class methods continue
+  to work, and the singleton ``.instance`` accessors on
+  ``FiberPipelineHandler`` / ``FiberTransactionHandler`` are
+  unchanged. The previous default of "allow all operations" when
+  capability flags were not set has been removed; every handler is now
+  expected to declare its capabilities explicitly via ``supports``.
+- ``Familia.dbclient`` and ``Familia::DataType#dbclient`` now route through ``FiberPipelineHandler`` before ``FiberTransactionHandler``, matching ``Horreum#dbclient``. With both handlers in the chain, attempting to mix pipeline and transaction contexts raises ``Familia::ConflictingContextError`` uniformly from every call site.
+
+Removed
+-------
+
+- ``Familia::DataType#direct_access`` has been removed. The method
+  was a legacy escape hatch for issuing raw Redis commands from
+  inside a DataType wrapper; it predates the chain-based routing of
+  ``Fiber[:familia_transaction]`` and ``Fiber[:familia_pipeline]``.
+  All in-tree call sites now go through the wrapper's own mutating
+  methods (which auto-route through the active transaction or
+  pipeline) or through the wrapper's ``transaction`` / ``pipelined``
+  blocks. If you were calling ``direct_access do |conn, key| ... end``,
+  replace it with either the DataType's own mutator or the
+  corresponding block API.
+
+Fixed
+-----
+
+- ``SortedSet#popmin`` and ``SortedSet#popmax`` now normalize an explicitly
+  passed ``nil`` count to the default of ``1``. Previously, calling
+  ``zset.popmin(nil)`` or ``zset.popmax(nil)`` would bypass the ``count == 1``
+  branch of the structural dispatch added in the prior commit, causing
+  redis-rb's flat ``[member, score]`` return shape to be iterated as if it
+  were a nested result — yielding a malformed pair. Omitting the argument
+  was and remains unaffected.
+
+- Restored ``require 'set'`` in ``lib/familia/horreum/management/audit.rb``. ``Set`` is autoloaded as a core class only on Ruby 3.4+; on Ruby 3.2/3.3 (the gem's supported floor) the require is mandatory for the five ``Set.new`` usages in that file.
+
+AI Assistance
+-------------
+
+- Claude Opus 4.5 analyzed Redis 7 command documentation and compared coverage
+  against existing Familia DataType implementations using parallel Explore agents.
+- Implementation performed by 5 parallel backend-dev agents, one per DataType.
+- Test coverage written by 5 parallel qa-automation-engineer agents focusing on
+  Familia-specific behavior (serialization, deserialization, aliases) rather than
+  re-testing redis-rb gem functionality.
+
+- Edge case identified by the Claude Code Review GitHub Action
+  (``.github/workflows/claude-code-review.yml``) when reviewing the
+  structural-dispatch change in commit ``010d5be``. Fix drafted and verified
+  by Claude Opus 4.7 under supervision.
+
+- Instance-scoped multi-index audit algorithm (bucket discovery,
+  scope existence batching, participation-driven missing detection),
+  ``repair_multi_indexes!``, the ``repair_all!`` robustness
+  refactor, and the accompanying tryouts coverage were authored
+  with Claude Code assistance against the #217 review branch.
+
+- Method split, alias wiring, bulk runner port from OTS, doc updates,
+  and expanded tryouts coverage (25 → 48 testcases) authored with
+  Claude Code.
+
+- Added the trace instrumentation in response to PR #263 review
+  feedback (Claude Code review bot) recommending tracing for
+  conflict detection events.
+
+- The handler refactor, ``direct_access`` removal, and changelog drafting were performed with Claude Code assistance while resolving review feedback on PR #263.
+
 .. _changelog-2.7.0:
 
 2.7.0 — 2026-05-13

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    familia (2.7.0)
+    familia (2.9.0)
       concurrent-ruby (~> 1.3)
       connection_pool (>= 2.4, < 4.0)
       csv (~> 3.3)
       json_schemer (~> 2.0)
       logger (~> 1.7)
       oj (~> 3.16)
-      redis (>= 4.8.1, < 6.0)
+      redis (>= 5.0, < 6.0)
       stringio (~> 3.1.1)
       uri-valkey (~> 1.4)
 

data/docs/guides/feature-housekeeping.md

@@ -3,7 +3,7 @@
 The Housekeeping feature provides a declarative DSL for registering named cleanup chores on Horreum models. It is designed for short-lived, repeated tidying against fields whose values have drifted over time -- not for versioned, one-shot migrations.
 
 > [!TIP]
-> Enable with `feature :housekeeping` and register cleanup blocks with `chore :name do |obj| ... end`. Run them with `obj.tidy!`. Iteration and persistence are the caller's responsibility.
+> Enable with `feature :housekeeping` and register cleanup blocks with `chore :name do |obj| ... end`. Run all of them with `obj.do_chores!` (aliased `tidy!`), or one with `obj.do_chore!(:name)`. Iteration and persistence are the caller's responsibility.
 
 ## Quick Start
 
@@ -27,8 +27,12 @@ class Organization < Familia::Horreum
 end
 
 org = Organization.from_identifier("acme-corp")
-org.tidy!
+org.do_chores!
 # => { standardize_planid: true }
+
+# Or run a single chore by name (returns the block's raw value):
+org.do_chore!(:standardize_planid)
+# => true
 ```
 
 ## When to Use
@@ -79,35 +83,43 @@ Run all registered chores, or one by name:
 ```ruby
 user = User.from_identifier("alice@example.com")
 
-user.tidy!
+user.do_chores!
 # => { downcase_email: true, default_timezone: nil }
 
-user.tidy!(:downcase_email)
-# => { downcase_email: true }
+user.tidy! # alias for do_chores!
+# => { downcase_email: nil, default_timezone: nil }
+
+user.do_chore!(:downcase_email)
+# => true
 ```
 
-The return value is a hash mapping chore name to the block's return value. A truthy result signals "modified"; `nil` or `false` signals "no-op". The feature does not interpret these values -- they are passed through for the caller's stats collection.
+`do_chores!` returns a hash mapping chore name to the block's return value. `do_chore!` returns the block's raw return value (not wrapped in a hash). A truthy result signals "modified"; `nil` or `false` signals "no-op". The feature does not interpret these values -- they are passed through for the caller's stats collection.
 
-### Iteration -- Caller's Responsibility
+### Iteration -- Bulk Runner
 
-The feature operates on a single instance. Bulk runs live in the consumer app:
+For running chores across every record, the feature ships a class-level `run_chores!` that iterates the `instances` collection in pipelined batches (via `load_multi`), executes each chore per record with error isolation, and returns a stats hash:
 
 ```ruby
-# nightly rake task
-namespace :data do
-  task tidy_orgs: :environment do
-    stats = Hash.new(0)
-    Organization.instances.each do |id|
-      org = Organization.find_by_id(id) or next
-      results = org.tidy!
-      results.each { |name, result| stats[name] += 1 if result }
-    end
-    puts stats.inspect
-  end
-end
+Organization.run_chores!
+# => {
+#      model: "Organization",
+#      scanned: 4200,
+#      chores: {
+#        standardize_planid: { modified: 37, errors: 0 },
+#        uppercase_country:  { modified: 102, errors: 1 },
+#      },
+#    }
+
+Organization.run_chores!(chore_name: :standardize_planid, limit: 500)
+# Filter to one chore and cap records scanned.
+
+Organization.run_chores!(batch_size: 50)
+# Tune the load_multi pipeline batch size (default: 100).
 ```
 
-The feature has no opinion about batching, SCAN vs KEYS, error aggregation, or scheduling -- the consumer app owns all of that.
+A truthy chore return increments `modified`; a raised exception increments `errors` (logged via `Familia.warn`) and iteration continues. The runner requires the class to expose `instances` (Horreum's default class-level sorted set) and `load_multi`.
+
+For scheduling, cross-model orchestration, custom logging, or non-default iteration (e.g. a configured allowlist of model classes), wrap `run_chores!` in your own job. The feature deliberately stays out of cron, multi-model discovery, and project-specific logging layers.
 
 ## Generated Method Reference
 
@@ -117,15 +129,18 @@ The feature has no opinion about batching, SCAN vs KEYS, error aggregation, or s
 |-------|--------|---------|
 | **Class** | `chore(name, &block)` | Register a chore |
 | | `chores` | Hash of registered chores |
-| **Instance** | `tidy!(name = nil)` | Run all (or one) chore; returns Hash |
+| | `run_chores!(chore_name:, limit:, batch_size:)` | Bulk runner across `instances`; returns stats hash |
+| **Instance** | `do_chore!(name)` | Run a single chore by name; returns the block's raw value |
+| | `do_chores!` | Run every registered chore; returns Hash |
+| | `tidy!` | Alias for `do_chores!` |
 
 ## Design Constraints
 
 1. **No implicit saves.** The block must call `save` (or `commit_fields`) itself. The feature does not auto-persist.
-2. **No iteration.** Operates on a single instance. There is no class-level `tidy_all!`.
+2. **Bulk via `run_chores!` only.** The feature operates on a single instance (`do_chore!`/`do_chores!`) plus one bulk runner (`run_chores!`) that iterates `instances`. Scheduling, multi-model orchestration, and custom logging stay in the consumer app.
 3. **No ordering.** Chores run in registration order, but should not depend on each other. If order matters, write one chore with sequential steps.
 4. **Idempotent by convention.** Use the conditional pattern (`if canonical && canonical != org.planid`) so a second run is a no-op.
-5. **Errors propagate.** The block can raise; the iteration code in the consumer app decides whether to rescue.
+5. **Errors isolate in `run_chores!`, propagate in `do_chore!`/`do_chores!`.** Single-instance methods let exceptions propagate; the bulk runner rescues per-record and increments the chore's `errors` counter so one failure doesn't halt the run.
 
 ## Common Patterns
 
@@ -150,7 +165,7 @@ class Customer < Familia::Horreum
   end
 end
 
-customer.tidy!
+customer.do_chores!
 # => { trim_whitespace: true, uppercase_country: nil }
 ```
 
@@ -176,28 +191,43 @@ chore :reconcile_billing do |account|
 end
 ```
 
-### Tracking Modified Records
+### Tracking Modified Records (Bulk)
+
+`run_chores!` already aggregates `modified` and `errors` counts per chore. Use it directly:
+
+```ruby
+report = Organization.run_chores!
+report[:chores].each do |name, counts|
+  puts "#{name}: #{counts[:modified]} modified, #{counts[:errors]} errors"
+end
+```
+
+### Custom Iteration (e.g. SCAN-Based)
+
+If `instances`-driven iteration isn't suitable (sharded data, custom scoping), drop down to `do_chore!`/`do_chores!`:
 
 ```ruby
 modified = []
 Organization.instances.each do |id|
-  org = Organization.find_by_id(id) or next
-  results = org.tidy!
+  org = Organization.find_by_identifier(id) or next
+  results = org.do_chores!
   modified << id if results.values.any?
 end
 puts "Modified #{modified.size} records: #{modified.inspect}"
 ```
 
-### Error Aggregation
+### Wrapping `run_chores!` for a Job Framework
 
 ```ruby
-errors = {}
-Organization.instances.each do |id|
-  org = Organization.find_by_id(id) or next
-  begin
-    org.tidy!
-  rescue => e
-    errors[id] = e.message
+class HousekeepingJob
+  def self.perform_for(klass)
+    report = klass.run_chores!(batch_size: 50)
+    StatsD.gauge("housekeeping.#{klass.name}.scanned", report[:scanned])
+    report[:chores].each do |chore, counts|
+      StatsD.increment("housekeeping.#{klass.name}.#{chore}.modified", counts[:modified])
+      StatsD.increment("housekeeping.#{klass.name}.#{chore}.errors",   counts[:errors])
+    end
+    report
   end
 end
 ```

data/docs/migrating/v2.9.0.md

@@ -0,0 +1,125 @@
+# Migrating to Familia 2.9.0
+
+This version introduces batch iteration primitives for DataTypes, enabling efficient enumeration over large Redis collections. It also includes breaking changes to method names for clarity.
+
+## Breaking Changes
+
+### Method Renames
+
+The multi-field update methods have been renamed to better reflect their purpose:
+
+```ruby
+# Before (2.8.x)
+user.batch_update(name: "Alice", email: "alice@example.com")
+user.batch_fast_write(name: "Alice", email: "alice@example.com")
+
+# After (2.9.0)
+user.multi_field_update(name: "Alice", email: "alice@example.com")
+user.multi_field_fast_write(name: "Alice", email: "alice@example.com")
+```
+
+**Migration**: Find and replace `batch_update` with `multi_field_update` and `batch_fast_write` with `multi_field_fast_write`.
+
+### MultiResult Namespace
+
+`MultiResult` has moved into the Familia namespace:
+
+```ruby
+# Before (2.8.x)
+result.is_a?(MultiResult)
+
+# After (2.9.0)
+result.is_a?(Familia::MultiResult)
+```
+
+**Migration**: Replace bare `MultiResult` references with `Familia::MultiResult`.
+
+## New Features
+
+### Enumerable Integration
+
+All collection DataTypes now include Ruby's `Enumerable` module, providing `each_slice`, `lazy`, `map`, `reduce`, `find`, and other stdlib methods:
+
+```ruby
+# Lazy iteration with transformation
+Org.instances.lazy.map { |id| id.upcase }.take(10).to_a
+
+# Batch processing with each_slice
+User.instances.each_slice(100) do |batch|
+  batch.each { |id| process(id) }
+end
+```
+
+### Filtered Iteration
+
+Each DataType now supports type-specific filters on `each`:
+
+```ruby
+# SortedSet: filter by score (timestamp) bounds
+Org.instances.each(since: 24.hours.ago, until: Time.now) do |id|
+  puts id
+end
+
+# HashKey: filter by field name pattern
+user.profile.each(matching: "pref_*") do |field, value|
+  puts "#{field}: #{value}"
+end
+
+# UnsortedSet: filter by member pattern
+user.tags.each(matching: "admin*") do |tag|
+  puts tag
+end
+```
+
+### each_record for Loading Horreum Instances
+
+`each_record` yields fully-loaded Horreum records instead of raw IDs:
+
+```ruby
+# Load records in batches of 100
+Org.instances.each_record(batch_size: 100) do |org|
+  org.tidy!  # org is a loaded Horreum instance
+end
+
+# Control pipelining depth separately from fetch batch size
+Org.instances.each_record(batch_size: 500, write_size: 50) do |org|
+  org.status!("active")
+end
+
+# Serial execution (no pipelining)
+Org.instances.each_record(batch_size: 100, write_size: nil) do |org|
+  org.complex_operation
+end
+```
+
+Ghost instances (keys that expired but remain in the `instances` sorted set) are automatically filtered and never reach the block.
+
+### BatchResult for Aggregated Operations
+
+`Familia::BatchResult` aggregates results from batch operations with per-record error isolation:
+
+```ruby
+result = Familia::BatchResult.collect(
+  Org.instances.each_record(batch_size: 100, since: 24.hours.ago)
+) do |org|
+  org.tidy!
+end
+
+result.scanned     # Total records yielded to block
+result.modified    # Count of truthy block returns
+result.errors      # Array of {id:, error:} for failed records
+result.duration_ms # Total execution time
+
+# Re-raise errors after completion
+result = Familia::BatchResult.collect(enum, strict: true) { |r| r.process! }
+```
+
+## Concurrent Mutation Behavior
+
+When iterating with `each` or `each_record`, be aware of Redis cursor semantics:
+
+- Items present from iteration start to end are guaranteed to be returned
+- Items added or removed mid-iteration may or may not appear
+- Blocks should be idempotent to handle potential duplicates
+
+This is inherent to ZSCAN/HSCAN/SSCAN and is documented, not a bug.

data/familia.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'json_schemer', '~> 2.0'
   spec.add_dependency 'logger', '~> 1.7'
   spec.add_dependency 'oj', '~> 3.16'
-  spec.add_dependency 'redis', '>= 4.8.1', '< 6.0'
+  spec.add_dependency 'redis', '>= 5.0', '< 6.0'
   spec.add_dependency 'stringio', '~> 3.1.1'
   spec.add_dependency 'uri-valkey', '~> 1.4'