familia 2.7.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b0138946cb9d48258b9f43b8a8a81aa895bfded213543feee354b3d383dd98a
-  data.tar.gz: bd5b6ee397c2ef19cef85fe7638ead34b5ed40a81c8362f539ed757d0d713ca2
+  metadata.gz: c6cb1ccd59d4290c1d75b70e114945180fc5dbb03aaeb405d841c250cd504179
+  data.tar.gz: c2bd7946e7e024c8322d0bf48bea39c22cd61c7690589007f9ab32e6f12e614d
 SHA512:
-  metadata.gz: 8108ee045d1f4f1bdc722a1b56a6518a32edebd18ae028dfdcd793a62044cc8bea509e06d8399179c11b1eeef971dd980d1bcd18654cd3a375af99b641c514a6
-  data.tar.gz: 395bcb27503bb30734d0d6e16fa8e95b33fa072dfaca56c2b9b06d33859c4cb915f766923a492cbdaae5407e45db2c76ee074a6c6d7aac245b822332f44d082c
+  metadata.gz: 54d3c3020c53fe01de9baf6af78fbcc1ffbea72a671b6e6269c08c9c5eaab786bb267514aa64212ff8ec854e0363cfb1c1de9b9c66674e57cb067ed419a8944b
+  data.tar.gz: d8b8ecd85ed1273c64ae75cab7559dee0ddb92fe5d552b60690c3a66ee9df93b3829aa32deef5438677ad9fb8d9acebb0bdbf071f3bccdb63161c4a772b1c021

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,181 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _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,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.7.0)
+    familia (2.8.0)
       concurrent-ruby (~> 1.3)
       connection_pool (>= 2.4, < 4.0)
       csv (~> 3.3)

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/lib/familia/connection/handlers.rb

@@ -38,37 +38,54 @@ module Familia
       end
     end
 
-    # Connection handler base class for Chain of Responsibility pattern.
-    # When no arguments are passed, all behaviour is based on the top
-    # Familia module itself. e.g. Familia.create_dbclient.
+    # Shared interface for connection handlers in the Chain of Responsibility.
     #
-    # Summary of Behaviors
+    # Including this module gives a handler class:
+    # * an instance-side `handle(uri)` stub that raises NotImplementedError, and
+    # * a small class-level DSL (`supports`) for declaring capability flags
+    #   (`allows_transaction`, `allows_pipelined`) read by the operation
+    #   guards in {Familia::Connection::TransactionCore} and
+    #   {Familia::Connection::PipelinedCore}.
     #
-    #   | Handler | Transaction | Pipeline | Ad-hoc Commands |
-    #   |---------|------------|----------|-----------------|
-    #   | **FiberTransaction** | Reentrant (same conn) | Error | Use transaction conn |
-    #   | **FiberConnection** | Error | Error | ✓ Allowed |
-    #   | **Provider** | ✓ New checkout | ✓ New checkout | ✓ New checkout |
-    #   | **Default** | ✓ With guards | ✓ With guards | ✓ Check mode |
-    #   | **Create** | ✓ Fresh conn | ✓ Fresh conn | ✓ Fresh conn |
+    # Capability flags default to `nil` when `supports` is not called — there
+    # is no implicit "allow all". Every handler is expected to declare its
+    # capabilities explicitly.
     #
-    # NOTE: Every subclass must provide values for the @allows_transaction
-    # and @allows_pipelined attributes.
+    # Summary of behaviours of the in-tree handlers:
     #
-    class BaseConnectionHandler
-      @allows_transaction = true
-      @allows_pipelined = true
-
-      class << self
-        attr_reader :allows_transaction, :allows_pipelined
+    #   | Handler            | Transaction       | Pipeline             | Ad-hoc Commands      |
+    #   |--------------------|-------------------|----------------------|----------------------|
+    #   | FiberPipeline      | Error             | Reentrant (same conn)| Use pipeline conn    |
+    #   | FiberTransaction   | Reentrant         | Error                | Use transaction conn |
+    #   | FiberConnection    | Error             | Error                | Allowed              |
+    #   | Provider           | New checkout      | New checkout         | New checkout         |
+    #   | Cached             | Error             | Error                | Allowed              |
+    #   | Create / Default   | Fresh conn        | Fresh conn           | Fresh conn           |
+    #   | ParentDelegation   | Delegated         | Delegated            | Delegated            |
+    #   | Standalone         | Allowed           | Allowed              | Allowed              |
+    #
+    module Handler
+      def self.included(base)
+        base.extend(ClassMethods)
       end
 
-      def initialize(familia_module = nil)
-        @familia_module = familia_module || Familia
+      def handle(_uri)
+        raise NotImplementedError, 'Subclasses must implement handle'
       end
 
-      def handle(uri)
-        raise NotImplementedError, 'Subclasses must implement handle'
+      # Class-level DSL injected into every handler class that includes Handler.
+      # Holds the capability flag readers and the `supports` declarator.
+      module ClassMethods
+        attr_reader :allows_transaction, :allows_pipelined
+
+        # Declare the operation modes this handler supports.
+        #
+        # @param transaction [Boolean, Symbol] true/false or :reentrant
+        # @param pipelined   [Boolean, Symbol] true/false or :reentrant
+        def supports(transaction: false, pipelined: false)
+          @allows_transaction = transaction
+          @allows_pipelined = pipelined
+        end
       end
     end
 
@@ -79,9 +96,14 @@ module Familia
     # Fresh connection each time - all operations safe (transactions,
     # pipelined, ad-hoc)
     #
-    class CreateConnectionHandler < BaseConnectionHandler
-      @allows_transaction = true
-      @allows_pipelined = true
+    class CreateConnectionHandler
+      include Handler
+
+      supports transaction: true, pipelined: true
+
+      def initialize(familia_module = nil)
+        @familia_module = familia_module || Familia
+      end
 
       def handle(uri)
         # Create new connection (no module-level caching)
@@ -101,9 +123,14 @@ module Familia
     # and also expected how they are to be used.
     # This is where connection pools live
     #
-    class ProviderConnectionHandler < BaseConnectionHandler
-      @allows_transaction = true
-      @allows_pipelined = true
+    class ProviderConnectionHandler
+      include Handler
+
+      supports transaction: true, pipelined: true
+
+      def initialize(familia_module = nil)
+        @familia_module = familia_module || Familia
+      end
 
       def handle(uri)
         return nil unless @familia_module.connection_provider
@@ -143,9 +170,14 @@ module Familia
     #       raise "Unknown operation: #{request.operation}"
     #     end
     #
-    class FiberConnectionHandler < BaseConnectionHandler
-      @allows_transaction = false
-      @allows_pipelined = false
+    class FiberConnectionHandler
+      include Handler
+
+      supports transaction: false, pipelined: false
+
+      def initialize(familia_module = nil)
+        @familia_module = familia_module || Familia
+      end
 
       def handle(uri)
         return nil unless Fiber[:familia_connection]
@@ -163,31 +195,80 @@ module Familia
       end
     end
 
-    # Checks for fiber-local transaction connections (highest priority for Horreum)
+    # Checks for fiber-local pipeline connections
+    #
+    # Returns the fiber-local pipeline connection when inside a pipelined block.
+    # Raises ConflictingContextError if both pipeline and transaction contexts
+    # are active — these are mutually exclusive operations.
+    #
+    # Reentrant pipeline - just yield the existing connection
+    # No new pipeline block, just participate in existing pipeline
+    #
+    class FiberPipelineHandler
+      include Handler
+
+      supports transaction: false, pipelined: :reentrant
+
+      # Singleton pattern for stateless handler
+      @instance = new.freeze
+
+      class << self
+        attr_reader :instance
+      end
+
+      def handle(_uri)
+        return nil unless Fiber[:familia_pipeline]
+
+        if Fiber[:familia_transaction]
+          Familia.trace :CONFLICTING_CONTEXT, _uri,
+                       'Pipeline handler detected active transaction context'
+          raise Familia::ConflictingContextError,
+            'Cannot mix pipeline and transaction contexts. ' \
+            'Restructure to use one or the other.'
+        end
+
+        Familia.trace :DBCLIENT_FIBER_PIPELINE, nil, 'Using fiber-local pipeline connection'
+        Fiber[:familia_pipeline]
+      end
+    end
+
+    # Checks for fiber-local transaction connections
     #
     # Key insight: Mark that we're in reentrant mode and also track of
     # depth. This allows nested transaction calls to be safely reentrant
     # without breaking Redis's single-level MULTI/EXEC.
     #
+    # Raises ConflictingContextError if both pipeline and transaction contexts
+    # are active — these are mutually exclusive operations.
+    #
     # Reentrant transaction - just yield the existing connection
     # No new MULTI/EXEC, just participate in existing transaction
     # Fiber[:familia_transaction_depth] ||= 0
     # Fiber[:familia_transaction_depth] += 1
     #
-    class FiberTransactionHandler < BaseConnectionHandler
-      @allows_transaction = :reentrant
-      @allows_pipelined = false
+    class FiberTransactionHandler
+      include Handler
+
+      supports transaction: :reentrant, pipelined: false
 
       # Singleton pattern for stateless handler
       @instance = new.freeze
 
-      def self.instance
-        @instance
+      class << self
+        attr_reader :instance
       end
 
       def handle(_uri)
         return nil unless Fiber[:familia_transaction]
 
+        if Fiber[:familia_pipeline]
+          Familia.trace :CONFLICTING_CONTEXT, _uri,
+                       'Transaction handler detected active pipeline context'
+          raise Familia::ConflictingContextError,
+            'Cannot mix pipeline and transaction contexts. ' \
+            'Restructure to use one or the other.'
+        end
+
         Familia.trace :DBCLIENT_FIBER_TRANSACTION, nil, 'Using fiber-local transaction connection'
         Fiber[:familia_transaction]
       end
@@ -205,9 +286,10 @@ module Familia
     #
     # CachedConnectionHandler - Single cached connection - block all multi-mode operations
     #
-    class CachedConnectionHandler < BaseConnectionHandler
-      @allows_transaction = false
-      @allows_pipelined = false
+    class CachedConnectionHandler
+      include Handler
+
+      supports transaction: false, pipelined: false
 
       def initialize(familia_module)
         @familia_module = familia_module
@@ -240,9 +322,10 @@ module Familia
     # @example Class-level DataType with parent
     #   User.global_users  # DataType that delegates to User.dbclient
     #
-    class ParentDelegationHandler < BaseConnectionHandler
-      @allows_transaction = true
-      @allows_pipelined = true
+    class ParentDelegationHandler
+      include Handler
+
+      supports transaction: true, pipelined: true
 
       def initialize(data_type)
         @data_type = data_type
@@ -281,9 +364,10 @@ module Familia
     # @example Standalone DataType with logical_database option
     #   cache = Familia::HashKey.new('app:cache', logical_database: 2)
     #
-    class StandaloneConnectionHandler < BaseConnectionHandler
-      @allows_transaction = true
-      @allows_pipelined = true
+    class StandaloneConnectionHandler
+      include Handler
+
+      supports transaction: true, pipelined: true
 
       def initialize(data_type)
         @data_type = data_type