familia 2.5.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 216f0e8232c1783dd031a43efce97bef6d53d095942da725892fdb4e78feb114
-  data.tar.gz: cc13a5871bce8ba8812e73142ef238e804cd67bbe6e672498feb2f72382d1a15
+  metadata.gz: 7b0138946cb9d48258b9f43b8a8a81aa895bfded213543feee354b3d383dd98a
+  data.tar.gz: bd5b6ee397c2ef19cef85fe7638ead34b5ed40a81c8362f539ed757d0d713ca2
 SHA512:
-  metadata.gz: 9f22dfe25d16e814e04ab07efbfc87c97ae0e62c964ec75daf9f7e9b318a04a96a6f8aec53b1727b85ecda6c82ea066100a09735b0fd932491a2642ddfde2007
-  data.tar.gz: f46f364c1288f5fe3d104210838bb68d033ed59b536d3d8ddb1d36d401e858f8204c85f94cea5561a75a1ffc05f002c33bc0cb46e1beea179e44d00614ec0e35
+  metadata.gz: 8108ee045d1f4f1bdc722a1b56a6518a32edebd18ae028dfdcd793a62044cc8bea509e06d8399179c11b1eeef971dd980d1bcd18654cd3a375af99b641c514a6
+  data.tar.gz: 395bcb27503bb30734d0d6e16fa8e95b33fa072dfaca56c2b9b06d33859c4cb915f766923a492cbdaae5407e45db2c76ee074a6c6d7aac245b822332f44d082c

data/.github/workflows/ci.yml

@@ -18,11 +18,16 @@ jobs:
 
     runs-on: ubuntu-24.04
 
+    continue-on-error: ${{ matrix.continue-on-error }}
+
     strategy:
-      fail-fast: true
+      fail-fast: false
       matrix:
         ruby: ["3.4", "3.5"]
         continue-on-error: [false]
+        include:
+          - ruby: "4.0"
+            continue-on-error: true
 
     services:
       redis:

data/CHANGELOG.rst

@@ -7,6 +7,150 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.7.0:
+
+2.7.0 — 2026-05-13
+==================
+
+Added
+-----
+
+- New ``housekeeping`` feature for ``Familia::Horreum``: a declarative DSL
+  (``chore :name do |obj| ... end``) for registering named cleanup blocks on
+  a model class, plus an instance method ``tidy!`` that runs all (or one)
+  registered chore against a single object. The feature owns registration
+  and per-instance execution only -- iteration, batching, scheduling and
+  error aggregation are the consumer application's responsibility, keeping
+  it distinct from ``Familia::Migration`` (which is for versioned, one-shot
+  transformations). Resolves #258.
+
+Documentation
+-------------
+
+- Added ``docs/guides/feature-housekeeping.md`` covering the API, the
+  ``housekeeping`` vs ``migration`` vs defensive-setter trade-off,
+  generated method reference, design constraints, and common patterns
+  (multiple chores, sequential steps in one chore, tracking modified
+  records, error aggregation).
+
+AI Assistance
+-------------
+
+- Drafted the housekeeping feature module, the tryouts test suite, and the
+  guide using Claude Code, working from the API proposal in issue #258 and
+  the existing ``feature-relationships.md`` and ``safe_dump.rb`` as style
+  templates.
+
+.. _changelog-2.6.0:
+
+2.6.0 — 2026-04-17
+==================
+
+Added
+-----
+
+- ``audit_multi_indexes`` detects drift in class-level multi-indexes via a
+  three-phase sweep (stale members, missing live objects, orphaned buckets).
+  Instance-scoped indexes (``within:``) return ``:not_implemented``. PR #221
+
+- ``audit_related_fields`` SCANs for instance-level collection keys
+  (``list``, ``set``, ``zset``, ``hashkey``) whose parent hash no longer
+  exists -- typically left behind by interrupted ``destroy!`` calls or
+  external key mutation. Class-level related fields are skipped. PR #221
+
+- ``audit_cross_references`` walks live identifiers against class-level
+  unique indexes to surface drift modes per-registry audits miss:
+  ``in_instances_missing_unique_index`` and
+  ``index_points_to_wrong_identifier`` (split-brain). PR #221
+
+- ``repair_related_fields!`` class method DELs orphaned collection keys
+  from an audit result and returns ``{removed_keys:, failed_keys:,
+  status:}``. ``repair_all!`` gains opt-in ``audit_collections:`` and
+  ``check_cross_refs:`` kwargs (both default ``false``); only
+  ``related_fields`` is auto-repaired, cross-reference drift is
+  reported for manual resolution. PR #221
+
+- ``Familia::AtomicOperations`` module exposing ``atomic_swap`` and
+  ``build_temp_key`` as reusable primitives for rebuild-then-swap
+  workflows (relies on native ``RENAME`` atomicity). PR #221
+
+- ``Horreum#atomic_write(&block)`` wraps scalar persistence and
+  collection mutations in a single MULTI/EXEC. Unlike
+  ``save_with_collections``, failures roll back scalars too. All
+  participating DataTypes must share ``logical_database``; mismatches
+  raise ``Familia::CrossDatabaseError``. (#220)
+
+Changed
+-------
+
+- ``health_check`` accepts new opt-in kwargs ``audit_collections:`` and
+  ``check_cross_refs:`` (both default ``false``). When omitted, the
+  corresponding report dimensions are ``nil`` and ``complete?`` returns
+  ``false`` until opted in. PR #221
+
+- ``atomic_swap`` and ``build_temp_key`` relocated from
+  ``Indexing::RebuildStrategies`` to ``Familia::AtomicOperations``.
+  Internal callers delegate through; downstream direct callers should
+  switch. Semantics preserved verbatim from PR #247. PR #221
+
+- ``health_check`` now reuses a single ``scan_identifiers`` +
+  ``load_multi`` pass across unique- and multi-index audits, reducing
+  SCANs from ``1 + N + M`` to ``2`` regardless of declared indexes.
+  Behavior and return shapes unchanged. PR #221
+
+- Audit methods pipeline batched Redis calls: ``audit_cross_references``
+  uses HMGET per batch instead of per-object HGET;
+  ``discover_multi_index_buckets`` and ``audit_single_related_field``
+  batch SCAN results in slices of 100 inside ``pipelined`` blocks,
+  collapsing M round trips to ~M/100. PR #221
+
+Fixed
+-----
+
+- ``AuditReport#healthy?`` now considers multi-index ``missing`` entries;
+  ``to_h`` / ``to_s`` include the ``missing`` count. Previously a report
+  could show ``issues_found`` while ``healthy?`` returned true. PR #221
+
+- ``atomic_write`` cross-database guard no longer false-positives when a
+  Horreum inherits its ``logical_database`` and a related field explicitly
+  sets ``logical_database: 0``. Both sides now resolve to concrete
+  integers before comparison. (#220)
+
+- ``atomic_write`` same-instance re-entrancy guard now uses a module-level
+  ``Mutex`` to serialise the ``@atomic_write_owner`` check-then-set,
+  closing a narrow race between concurrent entries. (#220)
+
+- ``atomic_write`` clears the dirty flag only when
+  ``MultiResult.successful?`` is true. Previously transactions whose
+  individual commands returned exception objects (MULTI swallows these)
+  could leave the object marked clean. (#220)
+
+- ``Horreum.scan_pattern``, ``discover_multi_index_buckets``, and
+  ``audit_instance_participations`` now respect ``Familia.delim`` instead
+  of hardcoding ``:``. Under a custom delim, every audit grounded in
+  these SCANs (instances, unique, multi, cross-references, participations)
+  silently saw zero keys and reported clean. PR #221
+
+AI Assistance
+-------------
+
+- Implementation and test coverage for the new audit dimensions
+  (``audit_multi_indexes``, ``audit_related_fields``,
+  ``audit_cross_references``, ``repair_related_fields!``), the
+  ``AuditReport`` extensions, the ``healthy?``/``to_h``/``to_s`` fix, the
+  ``Familia::AtomicOperations`` extraction, the ``health_check`` caching
+  refactor, and the four audit performance/correctness fixes
+  (delimiter-aware SCAN, batched HMGET, pipelined SMEMBERS, pipelined
+  EXISTS) were authored with AI assistance. PR #221
+
+- ``atomic_write`` design, implementation, tests, and review were
+  coordinated across Claude Code agents (``feature-dev:code-architect``,
+  ``backend-dev``, ``qa-automation-engineer``,
+  ``feature-dev:code-reviewer``). The reviewer caught a silent-corruption
+  gap in the cross-database guard; follow-up fixes (false-positive guard,
+  re-entrancy race, MultiResult success semantics) were surfaced by
+  ``gemini-code-assist`` and verified by the QA and reviewer agents. (#220)
+
 .. _changelog-2.5.0:
 
 2.5.0 — 2026-04-17

data/CLAUDE.md

@@ -250,6 +250,24 @@ plan.save                     # If this raises, features are already mutated
 
 **Cross-database limitation**: MULTI/EXEC transactions only work within a single Redis database number. If scalar fields and a collection use different `logical_database` values, they cannot share a transaction. The `save_with_collections` pattern handles this by sequencing the operations rather than wrapping them in MULTI.
 
+**Atomic pattern -- scalars and collections in one MULTI/EXEC:**
+```ruby
+plan.atomic_write do
+  plan.name = "Premium"               # Deferred: queued as HMSET by persist_to_storage
+  plan.features.clear                 # Immediate: queued as DEL in the open MULTI
+  plan.features.add("sso")            # Immediate: queued as SADD in the open MULTI
+end
+# Block body runs first, then persist_to_storage queues HMSET + index updates
+# + touch_instances!, then EXEC fires. All-or-nothing.
+```
+
+Unlike `save_with_collections` (which sequences two separate writes and cannot roll back scalars if a collection operation fails), `atomic_write` composes the existing `transaction` infrastructure so every command lands in one MULTI/EXEC. Collection mutations auto-route into the open transaction because `DataType#dbclient` honours `Fiber[:familia_transaction]`.
+
+Constraints:
+- All related DataTypes (instance-level and class-level) must share the parent Horreum's `logical_database`. A mismatch raises `Familia::CrossDatabaseError` -- fall back to `save_with_collections` in that case.
+- Cannot nest inside another `transaction` or `atomic_write` (raises `Familia::OperationModeError`).
+- Collection method return values inside the block are `Redis::Future` objects (inherent to MULTI) -- do not inspect them before EXEC.
+
 **Instances timeline**: The class-level `instances` sorted set is a timeline of last-modified times, not a registry. `persist_to_storage` (called by `save`) and `commit_fields`/`batch_update` all call `touch_instances!` to update the timestamp. Use `in_instances?(identifier)` for fast O(log N) checks without loading the object.
 
 ### Instances Timeline Lifecycle

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.5.0)
+    familia (2.7.0)
       concurrent-ruby (~> 1.3)
       connection_pool (>= 2.4, < 4.0)
       csv (~> 3.3)
@@ -81,7 +81,7 @@ GEM
     logger (1.7.0)
     mcp (0.8.0)
       json-schema (>= 4.1)
-    minitest (5.26.0)
+    minitest (5.27.0)
     oj (3.16.13)
       bigdecimal (>= 3.0)
       ostruct (>= 0.2)
@@ -188,7 +188,7 @@ GEM
     tty-screen (0.8.2)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
-    unicode-emoji (4.1.0)
+    unicode-emoji (4.2.0)
     uri-valkey (1.4.0)
     yard (0.9.37)
     zeitwerk (2.7.3)

data/changelog.d/20260514_034522_claude_review_familia_issue_217.rst

@@ -0,0 +1,46 @@
+Added
+~~~~~
+
+- 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.
+
+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.
+
+AI Assistance
+~~~~~~~~~~~~~
+
+- 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.

data/docs/guides/feature-housekeeping.md

@@ -0,0 +1,217 @@
+# Housekeeping Feature Guide
+
+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.
+
+## Quick Start
+
+```ruby
+class Organization < Familia::Horreum
+  feature :housekeeping
+
+  field :planid
+
+  chore :standardize_planid do |org|
+    canonical = case org.planid
+                when "pro", "Pro", "professional_v1" then "professional"
+                when "free", "Free", "basic"         then "free"
+                end
+    if canonical && canonical != org.planid
+      org.planid = canonical
+      org.save
+      true
+    end
+  end
+end
+
+org = Organization.from_identifier("acme-corp")
+org.tidy!
+# => { standardize_planid: true }
+```
+
+## When to Use
+
+| Tool | Use When |
+|------|----------|
+| `Familia::Migration::Base` | Versioned, one-shot transformation tracked across releases |
+| `feature :housekeeping` | Short-lived chore run nightly until data is clean, then removed |
+| Defensive code in setters | Permanent invariant enforced on every write |
+
+Housekeeping fills the gap between migrations (heavy, tracked) and inline coercion (permanent). Register a chore, run it on a schedule for a few days, verify clean data, then delete the chore and the defensive code that handled the messy values.
+
+## Core Capabilities
+
+### Registration -- Class-Level DSL
+
+Each chore is a named block bound to the model class:
+
+```ruby
+class User < Familia::Horreum
+  feature :housekeeping
+
+  field :email, :timezone
+
+  chore :downcase_email do |user|
+    next unless user.email && user.email != user.email.downcase
+    user.email = user.email.downcase
+    user.save
+    true
+  end
+
+  chore :default_timezone do |user|
+    next if user.timezone
+    user.timezone = "UTC"
+    user.save
+    true
+  end
+end
+
+User.chores.keys
+# => [:downcase_email, :default_timezone]
+```
+
+### Execution -- Single Instance
+
+Run all registered chores, or one by name:
+
+```ruby
+user = User.from_identifier("alice@example.com")
+
+user.tidy!
+# => { downcase_email: true, default_timezone: nil }
+
+user.tidy!(:downcase_email)
+# => { 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.
+
+### Iteration -- Caller's Responsibility
+
+The feature operates on a single instance. Bulk runs live in the consumer app:
+
+```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
+```
+
+The feature has no opinion about batching, SCAN vs KEYS, error aggregation, or scheduling -- the consumer app owns all of that.
+
+## Generated Method Reference
+
+### When a class declares `feature :housekeeping`
+
+| Class | Method | Purpose |
+|-------|--------|---------|
+| **Class** | `chore(name, &block)` | Register a chore |
+| | `chores` | Hash of registered chores |
+| **Instance** | `tidy!(name = nil)` | Run all (or one) chore; returns Hash |
+
+## 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!`.
+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.
+
+## Common Patterns
+
+### Multiple Independent Chores
+
+```ruby
+class Customer < Familia::Horreum
+  feature :housekeeping
+
+  chore :trim_whitespace do |c|
+    next unless c.name && c.name != c.name.strip
+    c.name = c.name.strip
+    c.save
+    true
+  end
+
+  chore :uppercase_country do |c|
+    next unless c.country && c.country != c.country.upcase
+    c.country = c.country.upcase
+    c.save
+    true
+  end
+end
+
+customer.tidy!
+# => { trim_whitespace: true, uppercase_country: nil }
+```
+
+### Sequential Steps in One Chore
+
+When step B depends on step A's result, keep them in one block:
+
+```ruby
+chore :reconcile_billing do |account|
+  changed = false
+  if account.plan_id == "legacy"
+    account.plan_id = "standard"
+    changed = true
+  end
+  if account.plan_id == "standard" && account.billing_cycle.nil?
+    account.billing_cycle = "monthly"
+    changed = true
+  end
+  if changed
+    account.save
+    true
+  end
+end
+```
+
+### Tracking Modified Records
+
+```ruby
+modified = []
+Organization.instances.each do |id|
+  org = Organization.find_by_id(id) or next
+  results = org.tidy!
+  modified << id if results.values.any?
+end
+puts "Modified #{modified.size} records: #{modified.inspect}"
+```
+
+### Error Aggregation
+
+```ruby
+errors = {}
+Organization.instances.each do |id|
+  org = Organization.find_by_id(id) or next
+  begin
+    org.tidy!
+  rescue => e
+    errors[id] = e.message
+  end
+end
+```
+
+## Best Practices
+
+1. **Keep chores short-lived.** Delete the registration once data is clean.
+2. **Use `||=` and conditional checks** so a second run is a no-op.
+3. **Save inside the block** -- the feature does not persist for you.
+4. **Return truthy on modification, nil on no-op** so callers can collect stats.
+5. **Prefer migrations for one-shot, versioned transformations.** Use housekeeping for ongoing tidying that can be run repeatedly.
+
+## See Also
+
+- [**Writing Migrations**](writing-migrations.md) - Versioned, one-shot data transformations
+- [**Field System**](field-system.md) - How field values are stored and serialized
+- [**Feature System**](feature-system.md) - How features are mixed into Horreum classes

data/docs/guides/index.md

@@ -37,9 +37,13 @@ Welcome to the comprehensive documentation for Familia v2.0. This guide collecti
 13. **[Quantization](feature-quantization.md)** - Time-based data bucketing for analytics
 14. **[Time Literals](time-literals.md)** - Time manipulation and formatting utilities
 
+### 🧹 Data Maintenance
+
+15. **[Housekeeping](feature-housekeeping.md)** - Declarative cleanup chores for drifted field values
+
 ### 🛠️ Implementation & Usage
 
-15. **[Optimized Loading](optimized-loading.md)** - Reduce Redis commands by 50-96% for bulk object loading _(new!)_
+16. **[Optimized Loading](optimized-loading.md)** - Reduce Redis commands by 50-96% for bulk object loading _(new!)_
 
 
 ## 🚀 Quick Start Examples

data/lib/familia/atomic_operations.rb

@@ -0,0 +1,86 @@
+# lib/familia/atomic_operations.rb
+#
+# frozen_string_literal: true
+
+# Familia
+#
+# A family warehouse for your keystore data.
+#
+module Familia
+  # AtomicOperations provides Redis utilities for atomic, zero-downtime data
+  # replacement. These primitives are datastore-level building blocks shared
+  # across index rebuilds, audit/repair routines, and any other code that
+  # needs to swap a key's contents without exposing a transient empty state.
+  #
+  # The canonical pattern:
+  # 1. Build replacement contents in a temporary key (see {.build_temp_key}).
+  # 2. Atomically swap it into place with {.atomic_swap}.
+  #
+  # All methods are module_function-style; call them directly on the module.
+  #
+  # @example Atomic index rebuild
+  #   temp_key = Familia::AtomicOperations.build_temp_key(final_key)
+  #   # ... populate temp_key ...
+  #   Familia::AtomicOperations.atomic_swap(temp_key, final_key, redis)
+  #
+  module AtomicOperations
+    # Builds a temporary key name for atomic swaps
+    #
+    # @param base_key [String] The final index key
+    # @return [String] Temporary key with timestamp suffix
+    #
+    def self.build_temp_key(base_key)
+      timestamp = Familia.now.to_i
+      "#{base_key}:rebuild:#{timestamp}"
+    end
+
+    # Performs atomic swap of temp key to final key.
+    #
+    # Non-empty rebuilds use Redis RENAME (>= 2.6), which atomically
+    # replaces final_key if it exists. Readers observe either the old
+    # index or the new one; there is no window in which final_key is
+    # absent. This avoids the partial-update, race-condition, and
+    # stale-visibility problems of a two-step DEL+RENAME sequence.
+    #
+    # Empty rebuilds (no temp key) intentionally DEL final_key so the
+    # live index reflects the empty result set. In that branch readers
+    # can observe final_key as absent -- this is the correct outcome for
+    # an index with zero members, not a transient gap.
+    #
+    # @param temp_key [String] The temporary key containing rebuilt index
+    # @param final_key [String] The live index key
+    # @param redis [Redis] The Redis connection
+    #
+    def self.atomic_swap(temp_key, final_key, redis)
+      # Check if temp key exists first - RENAME fails on non-existent keys.
+      # redis.exists returns Integer across all supported redis-rb versions;
+      # using > 0 also tolerates a future boolean return without breaking.
+      unless redis.exists(temp_key) > 0
+        Familia.info "[AtomicOp] No temp key to swap (empty result set)"
+        # Empty rebuild: remove the live index so reads reflect zero members.
+        # This is the one path where readers can legitimately see final_key
+        # as absent -- the index genuinely has no entries.
+        redis.del(final_key)
+        return
+      end
+
+      # RENAME atomically replaces final_key if it exists (Redis >= 2.6),
+      # so readers never observe a missing final_key during a non-empty
+      # swap. A preceding DEL would open a gap where concurrent HGETs
+      # return nil.
+      redis.rename(temp_key, final_key)
+      Familia.info "[AtomicOp] Atomic swap completed: #{temp_key} -> #{final_key}"
+    rescue Redis::CommandError => e
+      # If temp key doesn't exist, just log and return (already handled above)
+      if e.message.include?("no such key")
+        Familia.info "[AtomicOp] Temp key vanished during swap (concurrent operation?)"
+        return
+      end
+
+      # For other errors, preserve temp key for debugging
+      Familia.warn "[AtomicOp] Atomic swap failed: #{e.message}"
+      Familia.warn "[AtomicOp] Temp key preserved for debugging: #{temp_key}"
+      raise
+    end
+  end
+end

data/lib/familia/data_type.rb

@@ -150,6 +150,10 @@ module Familia
     # @raise [Familia::Problem] if Familia.strict_write_order is true
     #
     def warn_if_dirty!
+      # Suppress warnings while parent is inside atomic_write — scalar setters in the block
+      # make the object dirty by design, so firing warnings for each collection call is noise.
+      return if @parent_ref.respond_to?(:atomic_write_mode?) && @parent_ref.atomic_write_mode?
+
       return unless @parent_ref.respond_to?(:dirty?) && @parent_ref.dirty?
 
       dirty = @parent_ref.dirty_fields

data/lib/familia/errors.rb

@@ -43,6 +43,27 @@ module Familia
   # inside a transaction or pipeline
   class NestedTransactionError < OperationModeError; end
 
+  # Raised when atomic_write cannot include all DataType fields because
+  # they span multiple Redis databases (MULTI/EXEC cannot cross databases).
+  class CrossDatabaseError < OperationModeError
+    attr_reader :field_name, :field_database, :horreum_database
+
+    def initialize(field_name, field_database, horreum_database)
+      @field_name = field_name
+      @field_database = field_database
+      @horreum_database = horreum_database
+      super(build_message)
+    end
+
+    private
+
+    def build_message
+      "Cannot include field #{field_name} (logical_database: #{field_database}) in " \
+      "atomic_write: parent Horreum uses logical_database #{horreum_database}. " \
+      "MULTI/EXEC cannot span multiple databases."
+    end
+  end
+
   # Raised when attempting to reference a field that doesn't exist
   class UnknownFieldError < HorreumError; end