familia 2.2.0 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5608f472e264e8cbf6228e398d4a25517173e55ad0d7d10a2b74de31121b18f
-  data.tar.gz: 665996a35ca541c9884453c4c664d197b865bdba888e424cdd8a5a555df96a37
+  metadata.gz: 87748023c0bec120fe0b4936eac184ebe7f72651639b7ff87238782987654cc7
+  data.tar.gz: 5a3cbaf9000cf1e12cdcff9f2d35eecca57a010725e501de37485bda7cf214af
 SHA512:
-  metadata.gz: 22c1c274df0683053f768b418e7bc239fbc31fce4decf405af2e87c0b60f6f0c365c7dd88ba7a897746fffd785bdf15cfba71549ea8f32a0cdbf054eeb2467fc
-  data.tar.gz: b8bbe2ec2153c5de43b98bf9e03e80e94d494d056bbb0b65711f20b76fb77b99f5847be4b5420ccce5497ef18fb29dd38fd7f8329b67ce4928dff6d6b43546d4
+  metadata.gz: 21847a2154326c84d70557ee62ecfc4ea960f74ae6358e41b6c1d6fb7012d58034256a35dbc9aae26778a179cc3524e54012933a84191d2dc570f9d73c400cb8
+  data.tar.gz: da077f52d0ecbeba97779470f1e6d3a51934e7e7e3e03b05005e1187794f3ef23c9386aa15fe3747113c31982bf6e56add41948bd78a0d6d2867abaef883a31b

data/CHANGELOG.rst

@@ -7,6 +7,138 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.3.1:
+
+2.3.1 — 2026-03-06
+==================
+
+Fixed
+-----
+
+- Objects loaded from Redis via ``load``, ``find``, ``find_by_id``, ``find_by_dbkey``,
+  and ``load_multi`` no longer appear dirty. The ``instantiate_from_hash`` factory
+  now calls ``clear_dirty!`` after field assignment, matching the behavior of
+  ``initialize`` and ``refresh!``. Previously, every loaded object had all fields
+  marked dirty, causing false ``warn_if_dirty!`` warnings on subsequent collection
+  writes. Fixes `#225 <https://github.com/delano/familia/issues/225>`_.
+
+- Added ``warn_if_dirty!`` to 14 secondary collection mutation methods that were
+  missing the write-order check: ``remove_element``, ``pop``, ``move`` (UnsortedSet);
+  ``remove_element``, ``remrangebyrank``, ``remrangebyscore`` (SortedSet); ``pop``,
+  ``shift``, ``remove_element`` (ListKey); ``hsetnx``, ``remove_field``,
+  ``update``/``merge!`` (HashKey); ``value=``, ``setnx`` (JsonStringKey). Counter and
+  increment methods are intentionally excluded as they operate independently of the
+  parent's scalar lifecycle.
+
+- ``batch_update`` and ``batch_fast_write`` now update in-memory field values only
+  after the MULTI/EXEC transaction succeeds. Previously, setters ran inside the
+  transaction block, so a failed transaction could leave the object's in-memory
+  state diverged from Redis.
+
+AI Assistance
+-------------
+
+- Claude identified the one-line fix in ``instantiate_from_hash``, audited all
+  collection mutation paths for missing ``warn_if_dirty!`` calls, and triaged
+  the 29 candidates into tiers based on write-order risk. Also caught the
+  transaction-safety issue in ``batch_update``/``batch_fast_write`` during the
+  broader audit.
+
+.. _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

@@ -5,7 +5,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :test do
-  gem 'concurrent-ruby', '~> 1.3.5', require: false
+  gem 'concurrent-ruby', '~> 1.3.6', require: false
   gem 'ruby-prof'
   gem 'stackprof'
   gem 'timecop', require: false
@@ -15,12 +15,12 @@ end
 group :development, :test do
   gem 'benchmark', '~> 0.4', require: false
   gem 'debug', require: false
+  gem 'irb', '~> 1.15.2', require: false
   gem 'json_schemer', '~> 2.0', require: false
   gem 'rake', '~> 13.0', require: false
-  gem 'irb', '~> 1.15.2', require: false
   gem 'redcarpet', require: false
   gem 'reek', require: false
-  gem 'rubocop', '~> 1.81.1', require: false
+  gem 'rubocop', '~> 1.85.1', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-thread_safety', require: false
   gem 'ruby-lsp', require: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.2.0)
+    familia (2.3.1)
       concurrent-ruby (~> 1.3)
       connection_pool (>= 2.4, < 4.0)
       csv (~> 3.3)
@@ -14,6 +14,8 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
     benchmark (0.5.0)
@@ -65,6 +67,9 @@ GEM
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
     json (2.15.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
     json_schemer (2.5.0)
       bigdecimal
       hana (~> 1.3)
@@ -73,6 +78,8 @@ GEM
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
     minitest (5.26.0)
     oj (3.16.13)
       bigdecimal (>= 3.0)
@@ -87,10 +94,11 @@ GEM
     pp (0.6.3)
       prettyprint
     prettyprint (0.2.0)
-    prism (1.6.0)
+    prism (1.9.0)
     psych (5.2.6)
       date
       stringio
+    public_suffix (7.0.5)
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.1)
@@ -130,20 +138,21 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.6)
-    rubocop (1.81.1)
+    rubocop (1.85.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.47.1, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.47.1)
+    rubocop-ast (1.49.0)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
+      prism (~> 1.7)
     rubocop-performance (1.25.0)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
@@ -189,7 +198,7 @@ PLATFORMS
 
 DEPENDENCIES
   benchmark (~> 0.4)
-  concurrent-ruby (~> 1.3.5)
+  concurrent-ruby (~> 1.3.6)
   debug
   familia!
   irb (~> 1.15.2)
@@ -198,7 +207,7 @@ DEPENDENCIES
   rbnacl (~> 7.1, >= 7.1.1)
   redcarpet
   reek
-  rubocop (~> 1.81.1)
+  rubocop (~> 1.85.1)
   rubocop-performance
   rubocop-thread_safety
   ruby-lsp

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/serialization.rb

@@ -166,7 +166,7 @@ module Familia
         begin
           Familia::JsonSerializer.parse(val)
         rescue Familia::SerializerError
-          Familia.debug "[deserialize] Raw fallback in #{dbkey}: #{val.inspect[0..80]}"
+          Familia.warn "[deserialize] Raw fallback in #{dbkey} (#{val.class}, #{val.respond_to?(:bytesize) ? val.bytesize : '?'} bytes)"
           val
         end
       end

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
@@ -72,6 +77,7 @@ module Familia
     # @param val [Object] The value to set
     # @return [Integer] 1 if field is a new field and value was set, 0 if field already exists
     def hsetnx(field, val)
+      warn_if_dirty!
       ret = dbclient.hsetnx dbkey, field.to_s, serialize_value(val)
       update_expiration if ret == 1
       ret
@@ -95,13 +101,18 @@ 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
+      warn_if_dirty!
+      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
@@ -113,6 +124,7 @@ module Familia
     alias decrby decrement
 
     def update(hsh = {})
+      warn_if_dirty!
       raise ArgumentError, 'Argument to bulk_set must be a hash' unless hsh.is_a?(Hash)
 
       data = hsh.inject([]) { |ret, pair| ret << [pair[0], serialize_value(pair[1])] }.flatten