familia 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5608f472e264e8cbf6228e398d4a25517173e55ad0d7d10a2b74de31121b18f
-  data.tar.gz: 665996a35ca541c9884453c4c664d197b865bdba888e424cdd8a5a555df96a37
+  metadata.gz: 217726d80e8424a761dfa3aa0f565e9cdadd3da409654f5077226e1a85ae29ac
+  data.tar.gz: b9ce4a30717b220b78689332da5fe40fe790535029399fa2b0f9978dabd89ff5
 SHA512:
-  metadata.gz: 22c1c274df0683053f768b418e7bc239fbc31fce4decf405af2e87c0b60f6f0c365c7dd88ba7a897746fffd785bdf15cfba71549ea8f32a0cdbf054eeb2467fc
-  data.tar.gz: b8bbe2ec2153c5de43b98bf9e03e80e94d494d056bbb0b65711f20b76fb77b99f5847be4b5420ccce5497ef18fb29dd38fd7f8329b67ce4928dff6d6b43546d4
+  metadata.gz: ba13b9a6832ffce17a17548a398ca25f5588b6b7bc24e349151ddb3289173418947f833959fa83497e65d953ce781c51007c8a8516c42a5deab589e2e013100b
+  data.tar.gz: a2165e1aa07cdd4f7ca90f6c233dace66f9aba8647f652fb26f8ae484ee142506c218a57c57f1c9d86dc5a551958cd95a01be28de789b817ebd529280ee6c8f3

data/CHANGELOG.rst

@@ -7,6 +7,101 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.3.0:
+
+2.3.0 — 2026-02-26
+==================
+
+Added
+-----
+
+- ``touch_instances!`` and ``remove_from_instances!`` instance methods for
+  explicit instances timeline management. ``touch_instances!`` is idempotent
+  (ZADD updates the timestamp without duplicating).
+
+- ``in_instances?(identifier)`` class method for O(log N) membership checks
+  against the ``instances`` sorted set without loading the object.
+
+- Dirty tracking for scalar fields: ``dirty?``, ``dirty_fields``,
+  ``changed_fields``, ``clear_dirty!``. Setters automatically mark fields
+  dirty; state is cleared after ``save``, ``commit_fields``, and ``refresh!``.
+
+- ``warn_if_dirty!`` guard on collection write methods (``add``, ``push``,
+  ``[]=``, ``value=``). Warns when the parent Horreum has unsaved scalar
+  changes. Enable ``Familia.strict_write_order = true`` to raise instead.
+
+- ``ttl_report`` instance method on Expiration-enabled models. Returns a hash
+  showing TTL for the main key and all relation keys, useful for detecting
+  TTL drift.
+
+- ``debug_fields`` instance method on Horreum. Returns a diagnostic hash
+  showing Ruby value, stored JSON, and type for each persistent field.
+
+- Proactive consistency audit infrastructure for Horreum models. Every
+  subclass now has ``health_check``, ``audit_instances``,
+  ``audit_unique_indexes``, ``audit_multi_indexes``, and
+  ``audit_participations`` class methods to detect phantoms (timeline
+  entries without backing keys), missing entries (keys not in timeline),
+  stale index entries, and orphaned participation members. Issue #221.
+
+- ``AuditReport`` data structure (``Data.define``) that wraps audit
+  results with ``healthy?``, ``to_h`` (summary counts), and ``to_s``
+  (human-readable) methods for quick inspection and programmatic use.
+
+- Repair and rebuild operations: ``repair_instances!``,
+  ``rebuild_instances``, ``repair_indexes!``,
+  ``repair_participations!``, and ``repair_all!`` class methods.
+  ``rebuild_instances`` performs a full SCAN-based rebuild with atomic
+  swap via the existing ``RebuildStrategies`` infrastructure.
+
+- ``scan_keys`` helper on ManagementMethods for production-safe
+  enumeration of keys matching a class pattern via SCAN.
+
+- Participation audit reads actual collection contents (not the instances
+  timeline) and repairs use TYPE introspection to dispatch the correct
+  removal command per collection type.
+
+Changed
+-------
+
+- ``find_by_dbkey`` and ``find_by_identifier`` are now read-only.
+  They no longer call ``cleanup_stale_instance_entry`` as a side effect
+  when a key is missing. Ghost cleanup is the explicit responsibility
+  of the audit/repair layer or direct caller invocation.
+  ``cleanup_stale_instance_entry`` is now a public class method.
+
+- Fast writers (``field!``), ``batch_update``, ``batch_fast_write``,
+  and ``save_fields`` now clear dirty tracking state after a successful
+  database write. Note: this currently clears all dirty flags, even for
+  fields that were not part of the partial write. This known limitation
+  is documented in ``try/features/dirty_tracking_try.rb`` and will be
+  addressed in a future release.
+
+Fixed
+-----
+
+- ``commit_fields``, ``batch_update``, ``save_fields``, and fast writers now
+  touch the ``instances`` sorted set via ``touch_instances!``.
+  Previously, only ``save`` updated the timeline, leaving objects created
+  through other write paths invisible to ``instances.to_a`` enumeration.
+
+- Class-level ``destroy!`` now removes the identifier from the ``instances``
+  sorted set, preventing ghost entries after deletion.
+
+Documentation
+-------------
+
+- Added serialization encoding guide to CLAUDE.md showing how each DataType
+  serializes values and what raw Redis output looks like per type.
+
+AI Assistance
+-------------
+
+- Implementation, test authoring, and iterative debugging performed with
+  Claude Opus 4.6 assistance across dirty tracking, write-order guards,
+  TTL reporting, debug_fields, audit/repair infrastructure, and 211 test
+  cases across 14 audit files.
+
 .. _changelog-2.2.0:
 
 2.2.0 — 2026-02-23

data/CLAUDE.md

@@ -186,12 +186,96 @@ end
 - `active: true` (Boolean) stores as `"true"` in Redis and loads back as Boolean `true`
 - `metadata: {key: "value"}` (Hash) stores as JSON and loads back as Hash with proper types
 
+**Serialization by Type** (what you see in `redis-cli HGETALL` or `GET`):
+
+| Context | Serialize method | Ruby `"UK"` in Redis | Ruby `123` in Redis | Deserialize method |
+|---|---|---|---|---|
+| Horreum `field` | `serialize_value` (JSON) | `"\"UK\""` | `"123"` | `deserialize_value` (JSON parse) |
+| `StringKey` | `.to_s` (raw) | `"UK"` | `"123"` | raw string (no parse) |
+| `JsonStringKey` | JSON dump | `"\"UK\""` | `"123"` | JSON parse |
+| `List/Set/SortedSet/HashKey` values | `serialize_value` (JSON) | `"\"UK\""` | `"123"` | `deserialize_value` (JSON parse) |
+
+Key distinction: `StringKey` uses raw `.to_s` serialization (not JSON) to support Redis string operations like `INCR`, `DECR`, and `APPEND`. All other types use JSON encoding. When inspecting raw Redis output, a Horreum string field storing `"UK"` appears as `"\"UK\""` (double-quoted), while a `StringKey` storing `"UK"` appears as `"UK"` (no extra quotes).
+
+Use `debug_fields` on a Horreum instance to see Ruby values vs stored JSON side-by-side:
+```ruby
+user.debug_fields
+# => {"country" => {ruby: "UK", stored: "\"UK\"", type: "String"},
+#     "age"     => {ruby: 30,   stored: "30",      type: "Integer"}}
+```
+
 **Database Key Generation**: Automatic key generation using class name, identifier, and field/type names (aka dbkey). Pattern: `classname:identifier:fieldname`
 
 **Memory Efficiency**: Only non-nil values are stored in keystore database to optimize memory usage.
 
 **Thread Safety**: Data types are frozen after instantiation to ensure immutability.
 
+### Write Model: Deferred vs Immediate
+
+Familia has a two-tier write model. Understanding when data hits Redis is critical for avoiding inconsistencies.
+
+**Scalar fields** (defined with `field`) use deferred writes:
+- Normal setters (`user.name = "Alice"`) only update the in-memory instance variable. Nothing is written to Redis until `save`, `commit_fields`, or `batch_update` is called.
+- Fast writers (`user.name! "Alice"`) perform an immediate `HSET` on the object's hash key. Use these when you need a single field persisted without a full save cycle.
+
+**Collection fields** (defined with `list`, `set`, `zset`, `hashkey`) use immediate writes:
+- Every mutating method (`add`, `push`, `remove`, `clear`, `[]=`) executes the corresponding Redis command (SADD, RPUSH, ZREM, DEL, etc.) right away.
+- Collection fields live on separate Redis keys from the object's hash, so they cannot participate in the same MULTI/EXEC transaction as scalar fields.
+
+**Safe pattern -- scalars first, then collections:**
+```ruby
+plan.name = "Premium"
+plan.region = "US"
+plan.save  # HMSET for all scalar fields
+
+# Collections mutated AFTER scalars are committed
+plan.features.clear
+plan.features.add("sso")
+plan.features.add("priority_support")
+
+# Or use the convenience wrapper:
+plan.save_with_collections do
+  plan.features.clear
+  plan.features.add("sso")
+end
+```
+
+**Unsafe pattern -- collections before save:**
+```ruby
+plan.name = "Premium"
+plan.features.clear           # Immediate: Redis DEL
+plan.features.add("sso")     # Immediate: Redis SADD
+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.
+
+**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
+
+Every Horreum subclass has a class-level `instances` sorted set (a `class_sorted_set` with `reference: true`). This timeline maps identifiers to their last-write timestamp (ZADD score).
+
+**Write paths that touch instances** (call `touch_instances!`):
+- `save` / `save_if_not_exists!` (via `persist_to_storage`)
+- `commit_fields`
+- `batch_update`
+- `save_fields`
+- Fast writers (`field_name!`) via `FieldType` and `DefinitionMethods`
+
+**Write paths that remove from instances**:
+- Instance-level `destroy!` (via `remove_from_instances!`)
+- Class-level `destroy!(identifier)` (direct `instances.remove`)
+- `cleanup_stale_instance_entry` in `find_by_dbkey` (lazy, on-access pruning)
+
+**Ghost objects**: When a hash key expires via TTL but the identifier still lingers in `instances`, enumerating `instances.to_a` returns identifiers for objects that no longer exist. These are cleaned lazily: `find_by_dbkey` detects the missing key and calls `cleanup_stale_instance_entry`. Code that enumerates without loading (e.g. `instances.members`) will still see ghosts.
+
+**`in_instances?` vs `exists?`**:
+- `in_instances?(id)` checks the `instances` sorted set -- fast O(log N), but may return true for expired keys (ghost entries) or false for objects created outside Familia
+- `exists?(id)` checks the actual Redis hash key -- authoritative but requires a round-trip
+
+**`load` / `find_by_id` bypasses instances**: These methods read directly from the hash key via HGETALL. They do not consult `instances`. A key can exist in Redis without being in instances (e.g. created by `commit_fields` in an older version), and vice versa.
+
 ## Thread Safety Considerations
 
 ### Current Thread Safety Status (as of 2025-10-21)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.2.0)
+    familia (2.3.0)
       concurrent-ruby (~> 1.3)
       connection_pool (>= 2.4, < 4.0)
       csv (~> 3.3)

data/README.md

@@ -92,7 +92,7 @@ end
 
 ```ruby
 # Create and save
-user = User.create(email: 'alice@example.com', name: 'Alice', created_at: Time.now.to_i)
+user = User.create(email: 'alice@example.com', name: 'Alice', created_at: Familia.now)
 
 # Find by identifier
 user = User.load('alice@example.com')

data/docs/guides/feature-encrypted-fields.md

@@ -241,7 +241,7 @@ doc = SecureDocument.new(
   document_id: 'doc123',
   owner_id: 'user456',
   content: 'Sensitive document content',
-  created_at: Time.now.to_i
+  created_at: Familia.now.to_i
 )
 
 doc.save
@@ -551,9 +551,9 @@ class EncryptionMonitor
     total_time = 0
 
     Familia::Encryption.define_singleton_method(:encrypt) do |data, **opts|
-      start_time = Time.now
+      start_time = Familia.now
       result = original_encrypt.call(data, **opts)
-      total_time += (Time.now - start_time)
+      total_time += (Familia.now - start_time)
       call_count += 1
 
       if call_count % 100 == 0
@@ -813,7 +813,7 @@ class EncryptionHealthCheck
       end
 
       # Test encrypt/decrypt cycle
-      test_data = "health_check_#{Time.now.to_i}"
+      test_data = "health_check_#{Familia.now.to_i}"
       encrypted = Familia::Encryption.encrypt(test_data)
       decrypted = Familia::Encryption.decrypt(encrypted)
       results[:sample_encrypt_decrypt] = (decrypted == test_data)

data/docs/guides/feature-relationships-indexing.md

@@ -262,7 +262,7 @@ class Event < Familia::Horreum
   end
 end
 
-today = Time.now.strftime('%Y%m%d')
+today = Familia.now.strftime('%Y%m%d')
 todays_events = user.find_all_by_daily_partition(today)
 ```
 

data/docs/guides/feature-relationships-participation.md

@@ -175,7 +175,7 @@ active_tasks = project.tasks.range_by_score(1, '+inf')
 participates_in User, :sessions, score: :expires_at
 
 # Query active sessions
-now = Time.now.to_i
+now = Familia.now.to_i
 active = user.sessions.range_by_score(now, '+inf')
 ```
 

data/docs/guides/feature-relationships.md

@@ -91,7 +91,7 @@ class Task < Familia::Horreum
 
   # Lambda-based scoring
   participates_in Sprint, :tasks, score: -> {
-    priority * 100 + (Time.now - created_at) / 3600
+    priority * 100 + (Familia.now - created_at) / 3600
   }
 end
 

data/docs/guides/feature-system.md

@@ -245,7 +245,7 @@ module Familia
             field: field,
             old_value: instance_variable_was(field),
             new_value: instance_variable_get("@#{field}"),
-            timestamp: Time.now.to_f
+            timestamp: Familia.now.to_f
           }
 
           self.class.audit_log.append(change_record.to_json)

data/docs/guides/field-system.md

@@ -413,7 +413,7 @@ class AuditedFieldType < Familia::FieldType
 
         # Audit the change
         old_value = hget(field_name)
-        timestamp = Time.now.to_i
+        timestamp = Familia.now.to_i
 
         # Log the change
         puts "AUDIT: #{field_name} changed from #{old_value} to #{val} at #{timestamp}"
@@ -677,8 +677,8 @@ describe TimestampFieldType do
     expect(instance.created_at).to be_a(Time)
     expect(instance.created_at.to_s).to include("2024-01-01 12:00:00")
 
-    instance.created_at = Time.now
-    expect(instance.created_at).to be_a(Time)
+    instance.created_at = Familia.now
+    expect(instance.created_at).to be_a(Familia)
   end
 
   it "serializes to integer" do

data/docs/guides/optimized-loading.md

@@ -466,9 +466,9 @@ domains = Domain.load_multi(domain_ids).compact
 **Step 3**: Profile the change
 ```ruby
 # Add logging temporarily
-start = Time.now
+start = Familia.now
 domains = Domain.load_multi(domain_ids).compact
-duration = Time.now - start
+duration = Familia.now - start
 Rails.logger.info "Loaded #{domains.size} domains in #{duration}s"
 ```
 

data/examples/datatype_standalone.rb

@@ -232,7 +232,7 @@ class DemoApp
     session_data = {
       'user_id' => '12345',
       'username' => 'demo_user',
-      'login_time' => Time.now.to_i,
+      'login_time' => Familia.now.to_i,
       'preferences' => { 'theme' => 'dark', 'lang' => 'en' },
     }
 

data/examples/encrypted_fields.rb

@@ -126,7 +126,7 @@ puts 'Example 3: Performance optimization with request caching'
 entries = []
 
 # Without caching - each field derives keys independently
-start_time = Time.now
+start_time = Familia.now
 5.times do |i|
   private_key_pem = <<~PEM
     -----BEGIN PRIVATE KEY-----
@@ -145,10 +145,10 @@ start_time = Time.now
   entry.save
   entries << entry
 end
-no_cache_time = Time.now - start_time
+no_cache_time = Familia.now - start_time
 
 # With caching - reuses derived keys within the block
-start_time = Time.now
+start_time = Familia.now
 Familia::Encryption.with_request_cache do
   5.times do |i|
     private_key_pem = <<~PEM
@@ -169,7 +169,7 @@ Familia::Encryption.with_request_cache do
     entries << entry
   end
 end
-cached_time = Time.now - start_time
+cached_time = Familia.now - start_time
 
 puts "Encryption without caching: #{(no_cache_time * 1000).round(2)}ms"
 puts "Encryption with caching: #{(cached_time * 1000).round(2)}ms"

data/examples/json_usage_patterns.rb

@@ -58,7 +58,7 @@ mixed_data = {
   user: user.as_json,
   tags: user.tags.as_json,
   permissions: user.permissions.as_json,
-  meta: { timestamp: Time.now.to_i }
+  meta: { timestamp: Familia.now.to_i }
 }
 puts "   Manual preparation + JsonSerializer.dump:"
 puts Familia::JsonSerializer.dump(mixed_data)
@@ -77,7 +77,7 @@ using Familia::Refinements::DearJson
 mixed_hash = {
   user: user,                    # Familia object (will call as_json)
   tags: user.tags,              # Familia DataType (will call as_json)
-  meta: { timestamp: Time.now.to_i }  # Plain hash (passes through)
+  meta: { timestamp: Familia.now.to_i }  # Plain hash (passes through)
 }
 
 mixed_array = [

data/lib/familia/connection/behavior.rb

@@ -217,7 +217,7 @@ module Familia
       #   obj.pipelined do |conn|
       #     conn.hmset(obj.dbkey, obj.to_h)
       #     conn.hincrby(obj.dbkey, 'count', 1)
-      #     conn.hset(obj.dbkey, 'updated_at', Time.now.to_i)
+      #     conn.hset(obj.dbkey, 'updated_at', Familia.now.to_i)
       #   end
       #
       # @note Connection Inheritance:

data/lib/familia/connection/transaction_core.rb

@@ -40,7 +40,7 @@ module Familia
     #
     #   customer.transaction do
     #     customer.increment(:login_count)
-    #     customer.hset(:last_login, Time.now.to_i)
+    #     customer.hset(:last_login, Familia.now.to_i)
     #   end
     #
     # @example Incorrect Pattern: Save Inside Transaction

data/lib/familia/data_type/types/counter.rb

@@ -15,11 +15,20 @@ module Familia
     end
 
     def increment_if_less_than(threshold, amount = 1)
-      current = to_i
-      return false if current >= threshold
-
-      incrementby(amount)
-      true
+      lua = <<~LUA
+        local current = tonumber(redis.call('GET', KEYS[1]) or '0')
+        if current < tonumber(ARGV[1]) then
+          return redis.call('INCRBY', KEYS[1], ARGV[2])
+        end
+        return nil
+      LUA
+      result = dbclient.eval(lua, keys: [dbkey], argv: [threshold, amount])
+      if result
+        update_expiration
+        result.to_i
+      else
+        false
+      end
     end
 
     def atomic_increment_and_get(amount = 1)

data/lib/familia/data_type/types/hashkey.rb

@@ -19,7 +19,12 @@ module Familia
 
     # +return+ [Integer] Returns 1 if the field is new and added, 0 if the
     #  field already existed and the value was updated.
+    #
+    # @note This method executes a Redis HSET immediately, unlike scalar field
+    #   setters which are deferred until save. If the parent object has unsaved
+    #   scalar field changes, consider calling save first to avoid split-brain state.
     def []=(field, val)
+      warn_if_dirty!
       ret = dbclient.hset dbkey, field.to_s, serialize_value(val)
       update_expiration
       ret
@@ -95,13 +100,17 @@ module Familia
     # @param field [String] The field to remove
     # @return [Integer] The number of fields that were removed (0 or 1)
     def remove_field(field)
-      dbclient.hdel dbkey, field.to_s
+      ret = dbclient.hdel dbkey, field.to_s
+      update_expiration
+      ret
     end
     alias remove remove_field
     alias remove_element remove_field
 
     def increment(field, by = 1)
-      dbclient.hincrby(dbkey, field.to_s, by).to_i
+      ret = dbclient.hincrby(dbkey, field.to_s, by).to_i
+      update_expiration
+      ret
     end
     alias incr increment
     alias incrby increment

data/lib/familia/data_type/types/json_stringkey.rb

@@ -14,7 +14,7 @@ module Familia
   #     class_json_string :last_synced_at, default: 0.0
   #   end
   #
-  #   MyIndex.last_synced_at = Time.now.to_f  # Stored as JSON number
+  #   MyIndex.last_synced_at = Familia.now.to_f  # Stored as JSON number
   #   MyIndex.last_synced_at  #=> 1704067200.123 (Float preserved)
   #
   # @example Type preservation

data/lib/familia/data_type/types/listkey.rb

@@ -17,7 +17,11 @@ module Familia
       element_count.zero?
     end
 
+    # @note This method executes a Redis RPUSH immediately, unlike scalar field
+    #   setters which are deferred until save. If the parent object has unsaved
+    #   scalar field changes, consider calling save first to avoid split-brain state.
     def push *values
+      warn_if_dirty!
       echo :push, Familia.pretty_stack(limit: 1) if Familia.debug
       values.flatten.compact.each { |v| dbclient.rpush dbkey, serialize_value(v) }
       dbclient.ltrim dbkey, -@opts[:maxlength], -1 if @opts[:maxlength]
@@ -32,7 +36,11 @@ module Familia
     alias add_element <<
     alias add <<
 
+    # @note This method executes a Redis LPUSH immediately, unlike scalar field
+    #   setters which are deferred until save. If the parent object has unsaved
+    #   scalar field changes, consider calling save first to avoid split-brain state.
     def unshift *values
+      warn_if_dirty!
       values.flatten.compact.each { |v| dbclient.lpush dbkey, serialize_value(v) }
       # TODO: test maxlength
       dbclient.ltrim dbkey, 0, @opts[:maxlength] - 1 if @opts[:maxlength]
@@ -42,11 +50,15 @@ module Familia
     alias prepend unshift
 
     def pop
-      deserialize_value dbclient.rpop(dbkey)
+      ret = deserialize_value dbclient.rpop(dbkey)
+      update_expiration
+      ret
     end
 
     def shift
-      deserialize_value dbclient.lpop(dbkey)
+      ret = deserialize_value dbclient.lpop(dbkey)
+      update_expiration
+      ret
     end
 
     def [](idx, count = nil)
@@ -73,7 +85,9 @@ module Familia
     # @param count [Integer] Number of elements to remove (0 means all)
     # @return [Integer] The number of removed elements
     def remove_element(value, count = 0)
-      dbclient.lrem dbkey, count, serialize_value(value)
+      ret = dbclient.lrem dbkey, count, serialize_value(value)
+      update_expiration
+      ret
     end
     alias remove remove_element
 

data/lib/familia/data_type/types/sorted_set.rb

@@ -74,14 +74,14 @@ module Familia
     #   (NX+XX, GT+LT, NX+GT, NX+LT)
     #
     # @example Add new element with timestamp
-    #   metrics.add('pageview', Time.now.to_f)  #=> true
+    #   metrics.add('pageview', Familia.now.to_f)  #=> true
     #
     # @example Preserve original timestamp on subsequent saves
-    #   index.add(email, Time.now.to_f, nx: true)  #=> true
-    #   index.add(email, Time.now.to_f, nx: true)  #=> false (unchanged)
+    #   index.add(email, Familia.now.to_f, nx: true)  #=> true
+    #   index.add(email, Familia.now.to_f, nx: true)  #=> false (unchanged)
     #
     # @example Update timestamp only for existing entries
-    #   index.add(email, Time.now.to_f, xx: true)  #=> false (if doesn't exist)
+    #   index.add(email, Familia.now.to_f, xx: true)  #=> false (if doesn't exist)
     #
     # @example Only update if new score is higher (leaderboard)
     #   scores.add(player, 1000, gt: true)  #=> true (new entry)
@@ -102,7 +102,12 @@ module Familia
     #
     # @note INCR option is not supported. Use the increment method for ZINCRBY operations.
     #
+    # @note This method executes a Redis ZADD immediately, unlike scalar field
+    #   setters which are deferred until save. If the parent object has unsaved
+    #   scalar field changes, consider calling save first to avoid split-brain state.
+    #
     def add(val, score = nil, nx: false, xx: false, gt: false, lt: false, ch: false)
+      warn_if_dirty!
       score ||= Familia.now
 
       # Validate mutual exclusivity
@@ -261,15 +266,21 @@ module Familia
     end
 
     def remrangebyrank(srank, erank)
-      dbclient.zremrangebyrank dbkey, srank, erank
+      ret = dbclient.zremrangebyrank dbkey, srank, erank
+      update_expiration
+      ret
     end
 
     def remrangebyscore(sscore, escore)
-      dbclient.zremrangebyscore dbkey, sscore, escore
+      ret = dbclient.zremrangebyscore dbkey, sscore, escore
+      update_expiration
+      ret
     end
 
     def increment(val, by = 1)
-      dbclient.zincrby(dbkey, by, serialize_value(val)).to_f
+      ret = dbclient.zincrby(dbkey, by, serialize_value(val)).to_f
+      update_expiration
+      ret
     end
     alias incr increment
     alias incrby increment
@@ -285,7 +296,9 @@ module Familia
     # @return [Integer] The number of members that were removed (0 or 1)
     def remove_element(value)
       Familia.trace :REMOVE_ELEMENT, nil, "#{value}<#{value.class}>" if Familia.debug?
-      dbclient.zrem dbkey, serialize_value(value)
+      ret = dbclient.zrem dbkey, serialize_value(value)
+      update_expiration
+      ret
     end
     alias remove remove_element # deprecated
 

data/lib/familia/data_type/types/stringkey.rb

@@ -58,7 +58,11 @@ module Familia
       value.to_i
     end
 
+    # @note This method executes a Redis SET immediately, unlike scalar field
+    #   setters which are deferred until save. If the parent object has unsaved
+    #   scalar field changes, consider calling save first to avoid split-brain state.
     def value=(val)
+      warn_if_dirty!
       ret = dbclient.set(dbkey, serialize_value(val))
       update_expiration
       ret

data/lib/familia/data_type/types/unsorted_set.rb

@@ -19,7 +19,11 @@ module Familia
       element_count.zero?
     end
 
+    # @note This method executes a Redis SADD immediately, unlike scalar field
+    #   setters which are deferred until save. If the parent object has unsaved
+    #   scalar field changes, consider calling save first to avoid split-brain state.
     def add *values
+      warn_if_dirty!
       values.flatten.compact.each { |v| dbclient.sadd? dbkey, serialize_value(v) }
       update_expiration
       self
@@ -83,7 +87,9 @@ module Familia
     # @param value The value to remove from the set
     # @return [Integer] The number of members that were removed (0 or 1)
     def remove_element(value)
-      dbclient.srem dbkey, serialize_value(value)
+      ret = dbclient.srem dbkey, serialize_value(value)
+      update_expiration
+      ret
     end
     alias remove remove_element # deprecated
 
@@ -92,11 +98,15 @@ module Familia
     end
 
     def pop
-      deserialize_value(dbclient.spop(dbkey))
+      ret = deserialize_value(dbclient.spop(dbkey))
+      update_expiration
+      ret
     end
 
     def move(dstkey, val)
-      dbclient.smove dbkey, dstkey, serialize_value(val)
+      ret = dbclient.smove dbkey, dstkey, serialize_value(val)
+      update_expiration
+      ret
     end
 
     # Get one or more random members from the set