familia 2.3.0 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 217726d80e8424a761dfa3aa0f565e9cdadd3da409654f5077226e1a85ae29ac
-  data.tar.gz: b9ce4a30717b220b78689332da5fe40fe790535029399fa2b0f9978dabd89ff5
+  metadata.gz: 87748023c0bec120fe0b4936eac184ebe7f72651639b7ff87238782987654cc7
+  data.tar.gz: 5a3cbaf9000cf1e12cdcff9f2d35eecca57a010725e501de37485bda7cf214af
 SHA512:
-  metadata.gz: ba13b9a6832ffce17a17548a398ca25f5588b6b7bc24e349151ddb3289173418947f833959fa83497e65d953ce781c51007c8a8516c42a5deab589e2e013100b
-  data.tar.gz: a2165e1aa07cdd4f7ca90f6c233dace66f9aba8647f652fb26f8ae484ee142506c218a57c57f1c9d86dc5a551958cd95a01be28de789b817ebd529280ee6c8f3
+  metadata.gz: 21847a2154326c84d70557ee62ecfc4ea960f74ae6358e41b6c1d6fb7012d58034256a35dbc9aae26778a179cc3524e54012933a84191d2dc570f9d73c400cb8
+  data.tar.gz: da077f52d0ecbeba97779470f1e6d3a51934e7e7e3e03b05005e1187794f3ef23c9386aa15fe3747113c31982bf6e56add41948bd78a0d6d2867abaef883a31b

data/CHANGELOG.rst

@@ -7,6 +7,43 @@ 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

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.3.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/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/hashkey.rb

@@ -77,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
@@ -100,6 +101,7 @@ 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)
+      warn_if_dirty!
       ret = dbclient.hdel dbkey, field.to_s
       update_expiration
       ret
@@ -122,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

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

@@ -80,6 +80,7 @@ module Familia
     # @return [String] "OK" on success
     #
     def value=(val)
+      warn_if_dirty!
       ret = dbclient.set(dbkey, serialize_value(val))
       update_expiration
       ret
@@ -93,6 +94,7 @@ module Familia
     # @return [Boolean] true if the key was set, false if it already existed
     #
     def setnx(val)
+      warn_if_dirty!
       ret = dbclient.setnx(dbkey, serialize_value(val))
       update_expiration if ret
       ret

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

@@ -50,12 +50,14 @@ module Familia
     alias prepend unshift
 
     def pop
+      warn_if_dirty!
       ret = deserialize_value dbclient.rpop(dbkey)
       update_expiration
       ret
     end
 
     def shift
+      warn_if_dirty!
       ret = deserialize_value dbclient.lpop(dbkey)
       update_expiration
       ret
@@ -85,6 +87,7 @@ 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)
+      warn_if_dirty!
       ret = dbclient.lrem dbkey, count, serialize_value(value)
       update_expiration
       ret

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

@@ -266,12 +266,14 @@ module Familia
     end
 
     def remrangebyrank(srank, erank)
+      warn_if_dirty!
       ret = dbclient.zremrangebyrank dbkey, srank, erank
       update_expiration
       ret
     end
 
     def remrangebyscore(sscore, escore)
+      warn_if_dirty!
       ret = dbclient.zremrangebyscore dbkey, sscore, escore
       update_expiration
       ret
@@ -295,6 +297,7 @@ module Familia
     # @param value The value to remove from the sorted set
     # @return [Integer] The number of members that were removed (0 or 1)
     def remove_element(value)
+      warn_if_dirty!
       Familia.trace :REMOVE_ELEMENT, nil, "#{value}<#{value.class}>" if Familia.debug?
       ret = dbclient.zrem dbkey, serialize_value(value)
       update_expiration

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

@@ -87,6 +87,7 @@ 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)
+      warn_if_dirty!
       ret = dbclient.srem dbkey, serialize_value(value)
       update_expiration
       ret
@@ -98,12 +99,14 @@ module Familia
     end
 
     def pop
+      warn_if_dirty!
       ret = deserialize_value(dbclient.spop(dbkey))
       update_expiration
       ret
     end
 
     def move(dstkey, val)
+      warn_if_dirty!
       ret = dbclient.smove dbkey, dstkey, serialize_value(val)
       update_expiration
       ret

data/lib/familia/features/encrypted_fields/encrypted_field_type.rb

@@ -24,6 +24,8 @@ module Familia
 
       handle_method_conflict(klass, :"#{method_name}=") do
         klass.define_method :"#{method_name}=" do |value|
+          old_value = instance_variable_get(:"@#{field_name}")
+
           if value.nil?
             instance_variable_set(:"@#{field_name}", nil)
           elsif value.is_a?(::String) && value.empty?
@@ -44,6 +46,9 @@ module Familia
             concealed = ConcealedString.new(encrypted, self, field_type)
             instance_variable_set(:"@#{field_name}", concealed)
           end
+
+          # Track the change for dirty-tracking (only for Horreum instances)
+          mark_dirty!(field_name, old_value) if respond_to?(:mark_dirty!)
         end
       end
     end

data/lib/familia/horreum/dirty_tracking.rb

@@ -2,6 +2,8 @@
 #
 # frozen_string_literal: true
 
+require 'concurrent/map'
+
 module Familia
   class Horreum
     # DirtyTracking - Tracks in-memory field changes since last save/refresh.
@@ -15,6 +17,13 @@ module Familia
     # Fields are marked dirty automatically by the setter defined in FieldType.
     # Dirty state is cleared after save, commit_fields, and refresh operations.
     #
+    # Uses Concurrent::Map for thread-safe access to the dirty fields tracker
+    # without requiring explicit mutex locks. The map is eagerly initialized
+    # in Horreum#initialize and the allocate-based load paths so that no
+    # lazy ||= race exists under normal usage. The ||= fallbacks in each
+    # method are a safety net for subclasses that override initialize
+    # without calling super (a documented anti-pattern).
+    #
     # @example
     #   user = User.new(name: "Alice")
     #   user.dirty?            # => false (just initialized)
@@ -37,15 +46,10 @@ module Familia
       # @return [void]
       #
       def mark_dirty!(field_name, old_value)
-        @dirty_fields ||= {}
-        field_sym = field_name.to_sym
-
-        # Only record the original old value on the first mutation.
-        # Subsequent changes keep the original baseline so changed_fields
-        # shows [original, current] rather than [previous, current].
-        unless @dirty_fields.key?(field_sym)
-          @dirty_fields[field_sym] = old_value
-        end
+        # Safety net for subclasses that override initialize without calling super
+        @dirty_fields ||= Concurrent::Map.new
+        # Atomic: only stores old_value if field_sym is not already tracked.
+        @dirty_fields.put_if_absent(field_name.to_sym, old_value)
       end
 
       # Whether any fields (or a specific field) have unsaved changes.
@@ -54,8 +58,7 @@ module Familia
       # @return [Boolean]
       #
       def dirty?(field = nil)
-        @dirty_fields ||= {}
-
+        @dirty_fields ||= Concurrent::Map.new
         if field
           @dirty_fields.key?(field.to_sym)
         else
@@ -68,7 +71,7 @@ module Familia
       # @return [Array<Symbol>] field names with unsaved changes
       #
       def dirty_fields
-        @dirty_fields ||= {}
+        @dirty_fields ||= Concurrent::Map.new
         @dirty_fields.keys
       end
 
@@ -80,11 +83,13 @@ module Familia
       # @return [Hash{Symbol => Array(Object, Object)}]
       #
       def changed_fields
-        @dirty_fields ||= {}
-        @dirty_fields.each_with_object({}) do |(field_name, old_value), result|
+        @dirty_fields ||= Concurrent::Map.new
+        result = {}
+        @dirty_fields.each_pair do |field_name, old_value|
           current_value = instance_variable_get(:"@#{field_name}")
           result[field_name] = [old_value, current_value]
         end
+        result
       end
 
       # Clears dirty tracking state for all or specific fields.
@@ -98,8 +103,9 @@ module Familia
       # @return [void]
       #
       def clear_dirty!(*field_names)
+        @dirty_fields ||= Concurrent::Map.new
         if field_names.empty?
-          @dirty_fields = {}
+          @dirty_fields.clear
         else
           field_names.each { |f| @dirty_fields.delete(f.to_sym) }
         end

data/lib/familia/horreum/management.rb

@@ -748,8 +748,13 @@ module Familia
       # @api private
       def instantiate_from_hash(obj_hash)
         instance = allocate
+        instance.instance_variable_set(:@dirty_fields, Concurrent::Map.new)
         instance.send(:initialize_relatives)
         instance.send(:initialize_with_keyword_args_deserialize_value, **obj_hash)
+        # Object was just loaded from Redis, so it matches DB state exactly.
+        # Clear dirty flags set during field assignment above, mirroring what
+        # initialize (horreum.rb:246) and refresh! (persistence.rb:608) do.
+        instance.send(:clear_dirty!)
         instance
       end
 
@@ -794,6 +799,7 @@ module Familia
 
         # Use a temporary instance for deserialization (needs serialize_value/deserialize_value)
         temp = allocate
+        temp.instance_variable_set(:@dirty_fields, Concurrent::Map.new)
         temp.send(:initialize_relatives)
 
         raw_hash.each_with_object({}) do |(field, raw_val), result|

data/lib/familia/horreum/persistence.rb

@@ -343,15 +343,14 @@ module Familia
         update_expiration = kwargs.delete(:update_expiration) { true }
         fields = kwargs
 
+        guard_allowed_fields!(fields.keys)
         Familia.trace :BATCH_UPDATE, nil, fields.keys if Familia.debug?
 
         result = transaction do |_conn|
-          # 1. Update all fields atomically
+          # 1. Update all fields atomically (Redis only, no in-memory mutation)
           fields.each do |field, value|
             prepared_value = serialize_value(value)
             hset field, prepared_value
-            # Update instance variable to keep object in sync
-            send("#{field}=", value) if respond_to?("#{field}=")
           end
 
           # 2. Update expiration in same transaction
@@ -362,7 +361,14 @@ module Familia
           touch_instances!
         end
 
-        clear_dirty!(*fields.keys) unless result.nil?
+        # Update in-memory state only after transaction succeeds,
+        # so a failed transaction never leaves the object diverged.
+        if result.is_a?(MultiResult) && result.successful?
+          fields.each do |field, value|
+            send("#{field}=", value) if respond_to?("#{field}=")
+          end
+          clear_dirty!(*fields.keys)
+        end
 
         result
       end
@@ -394,13 +400,13 @@ module Familia
         fields = kwargs
 
         raise ArgumentError, 'No fields specified' if fields.empty?
+        guard_allowed_fields!(fields.keys)
 
         Familia.trace :BATCH_FAST_WRITE, nil, fields.keys if Familia.debug?
 
-        # Build serialized hash and update instance variables
+        # Serialize values before the transaction (read-only on instance)
         serialized = {}
         fields.each do |field, value|
-          send(:"#{field}=", value) if respond_to?(:"#{field}=")
           serialized[field] = serialize_value(value)
         end
 
@@ -412,7 +418,14 @@ module Familia
           touch_instances!
         end
 
-        clear_dirty!(*fields.keys) unless result.nil?
+        # Update in-memory state only after transaction succeeds,
+        # so a failed transaction never leaves the object diverged.
+        if result.is_a?(MultiResult) && result.successful?
+          fields.each do |field, value|
+            send(:"#{field}=", value) if respond_to?(:"#{field}=")
+          end
+          clear_dirty!(*fields.keys)
+        end
 
         self
       end
@@ -477,8 +490,8 @@ module Familia
       #   # => #<User:0x007f8a1c8b0a28 @name="John", @email="john@example.com", @age=30>
       #
       def apply_fields(**fields)
+        guard_allowed_fields!(fields.keys)
         fields.each do |field, value|
-          # Apply the field value if the setter method exists
           send("#{field}=", value) if respond_to?("#{field}=")
         end
         self
@@ -695,6 +708,27 @@ module Familia
 
       private
 
+      # Validates that all field names are declared Familia fields.
+      #
+      # Prevents mass-assignment of arbitrary setter methods (e.g. role=,
+      # admin=) that are not declared via the `field` or `transient` DSL.
+      # This is a defense-in-depth measure for downstream callers that may
+      # inadvertently pass unsanitized input to batch methods.
+      #
+      # @param names [Array<Symbol, String>] field names to validate
+      # @raise [ArgumentError] if any name is not a declared field
+      # @return [void]
+      #
+      def guard_allowed_fields!(names)
+        allowed = self.class.field_method_map.keys
+        unknown = names.map(&:to_sym) - allowed
+        return if unknown.empty?
+
+        raise ArgumentError,
+          "Undeclared fields for #{self.class}: #{unknown.join(', ')}. " \
+          "Only fields defined with `field` or `transient` are mass-assignable."
+      end
+
       # Reset all transient fields to nil
       #
       # This method ensures that transient fields return to their uninitialized

data/lib/familia/horreum.rb

@@ -189,6 +189,7 @@ module Familia
     #   `Session.new({sessid: "abc123", custid: "user456"})` # legacy hash (robust)
     #
     def initialize(*args, **kwargs)
+      @dirty_fields = Concurrent::Map.new
       start_time = Familia.now_in_μs if Familia.debug?
       Familia.trace :INITIALIZE, nil, "Initializing #{self.class}" if Familia.debug?
       initialize_relatives

data/lib/familia/version.rb

@@ -4,5 +4,5 @@
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.3.0'
+  VERSION = '2.3.1'
 end

data/try/features/dirty_tracking_try.rb

@@ -3,6 +3,7 @@
 # frozen_string_literal: true
 
 require_relative '../support/helpers/test_helpers'
+require 'base64'
 
 class DirtyTrackUser < Familia::Horreum
   identifier_field :email
@@ -12,6 +13,19 @@ class DirtyTrackUser < Familia::Horreum
   field :active
 end
 
+# Encrypted field model for dirty tracking tests
+# Encryption keys must be configured before defining the class
+Familia.config.encryption_keys = { v1: Base64.strict_encode64('a' * 32) }
+Familia.config.current_key_version = :v1
+
+class DirtyTrackSecureUser < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :user_id
+  field :user_id
+  field :display_name
+  encrypted_field :secret_token
+end
+
 @user = DirtyTrackUser.new(email: 'alice@example.com', name: 'Alice', age: 30, active: true)
 
 ## Freshly constructed object is not dirty
@@ -181,19 +195,13 @@ end
 @wp.dirty?
 #=> false
 
-# Known bug: clear_dirty! blanket-resets all dirty state
+# Selective clear_dirty! for partial write paths
 #
-# Every write path calls clear_dirty! after persisting, but partial write
-# paths (fast writers, save_fields, batch_update) only persist a subset of
-# fields. The blanket reset incorrectly clears dirty state for fields that
-# were NOT persisted, causing the object to report as clean when it still
-# has unsaved changes.
-#
-# These tests document the correct behavior. They are expected to FAIL
-# with the current implementation until clear_dirty! is fixed to only
-# clear the fields that were actually written.
+# Partial write paths (fast writers, save_fields, batch_update) only persist
+# a subset of fields. clear_dirty! selectively clears only the fields that
+# were actually written, preserving dirty state for unwritten fields.
 
-## Fast writer clears unrelated dirty fields (BUG: should preserve them)
+## Fast writer preserves dirty state for unwritten fields
 # When fields A and B are both dirty and only A is fast-written,
 # field B should still be marked dirty because it was not persisted.
 @bug1 = DirtyTrackUser.new(email: 'bug1@example.com', name: 'Original', age: 20)
@@ -217,7 +225,7 @@ end
 @bug1.dirty_fields
 #=> [:age]
 
-## save_fields clears unrelated dirty fields (BUG: should preserve them)
+## save_fields preserves dirty state for unwritten fields
 # When fields A and B are both dirty and only A is saved via save_fields,
 # field B should still be marked dirty because it was not persisted.
 @bug2 = DirtyTrackUser.new(email: 'bug2@example.com', name: 'Original', age: 20)
@@ -497,8 +505,91 @@ end
 @clean.dirty?
 #=> false
 
+# Issue #225: Objects loaded from Redis should not be dirty
+# instantiate_from_hash (used by load, find_by_dbkey) was missing
+# clear_dirty!, so loaded objects appeared dirty even though they matched DB state.
+
+## Object loaded via load should not be dirty
+@loaded_user = DirtyTrackUser.new(email: 'load-clean@example.com', name: 'LoadClean', age: 25, active: true)
+@loaded_user.save
+@reloaded = DirtyTrackUser.load('load-clean@example.com')
+@reloaded.dirty?
+#=> false
+
+## Loaded object should have empty dirty_fields
+@reloaded.dirty_fields
+#=> []
+
+## Loaded object should have empty changed_fields
+@reloaded.changed_fields
+#=> {}
+
+## Object loaded via find_by_dbkey should not be dirty
+@found = DirtyTrackUser.find_by_dbkey(DirtyTrackUser.dbkey('load-clean@example.com'))
+@found.dirty?
+#=> false
+
+## Modifying a loaded object marks it dirty as expected
+@reloaded.name = 'Modified'
+@reloaded.dirty?
+#=> true
+
+## Loaded object dirty_fields reflects the modification
+@reloaded.dirty_fields
+#=> [:name]
+
+# Encrypted field dirty tracking tests
+#
+# Encrypted field setters (EncryptedFieldType#define_setter) use
+# instance_variable_set directly without calling mark_dirty!. This means
+# setting an encrypted field does not mark the object as dirty, even though
+# encrypted fields ARE persisted to Redis just like regular fields.
+#
+# These tests document the correct behavior and should FAIL until
+# mark_dirty! is added to the encrypted field setter.
+
+## Setting an encrypted field should mark object as dirty
+@enc1 = DirtyTrackSecureUser.new(user_id: 'enc-dirty-1', display_name: 'EncUser1')
+@enc1.save
+@enc1 = DirtyTrackSecureUser.load('enc-dirty-1')
+@enc1.secret_token = 'my-secret-abc'
+@enc1.dirty?
+#=> true
+
+## Encrypted field should appear in dirty_fields
+@enc1.dirty_fields
+#=> [:secret_token]
+
+## Encrypted field should appear in changed_fields
+@enc1.changed_fields.key?(:secret_token)
+#=> true
+
+## Save should clear encrypted field dirty state
+@enc2 = DirtyTrackSecureUser.new(user_id: 'enc-dirty-2', display_name: 'EncUser2')
+@enc2.save
+@enc2 = DirtyTrackSecureUser.load('enc-dirty-2')
+@enc2.secret_token = 'another-secret'
+@enc2.save
+@enc2.dirty?
+#=> false
+
+## Mixed dirty tracking: both regular and encrypted fields appear in dirty_fields
+@enc3 = DirtyTrackSecureUser.new(user_id: 'enc-dirty-3', display_name: 'EncUser3')
+@enc3.save
+@enc3 = DirtyTrackSecureUser.load('enc-dirty-3')
+@enc3.display_name = 'UpdatedName'
+@enc3.secret_token = 'secret-xyz'
+@enc3.dirty_fields.sort
+#=> [:display_name, :secret_token]
+
 ## Teardown
 DirtyTrackUser.instances.members.each do |id|
   obj = DirtyTrackUser.new(id)
   obj.destroy! rescue nil
 end
+DirtyTrackSecureUser.instances.members.each do |id|
+  obj = DirtyTrackSecureUser.new(id)
+  obj.destroy! rescue nil
+end
+Familia.config.encryption_keys = nil
+Familia.config.current_key_version = nil

data/try/features/relationships/relationships_performance_try.rb

@@ -157,7 +157,10 @@ instances = 100.times.map { |i| PerfDomain.new(domain_id: "mem_test_#{i}") }
 after_instances = ObjectSpace.count_objects[:T_OBJECT]
 
 # Should not have created excessive objects (relationship metadata is shared)
-(after_instances - before_instances) < 250  # Allow for reasonable, 2.5x overhead
+# Threshold accommodates per-instance allocations (Concurrent::Map for dirty
+# tracking, DataType relatives, etc.) which vary across Ruby versions.
+# Ruby 3.5+ allocates more T_OBJECTs internally per instance.
+(after_instances - before_instances) < 800
 #=> true
 
 ## Class-level relationship metadata should be constant size

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.3.1
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -330,8 +330,6 @@ files:
 - lib/middleware/database_command_counter.rb
 - lib/middleware/database_logger.rb
 - lib/multi_result.rb
-- pr_agent.toml
-- pr_compliance_checklist.yaml
 - try/audit/audit_instances_try.rb
 - try/audit/audit_report_try.rb
 - try/audit/audit_unique_indexes_try.rb

data/pr_agent.toml

@@ -1,36 +0,0 @@
-# Qodo Merge Configuration
-# Documentation: https://qodo-merge-docs.qodo.ai/usage-guide/configuration_options/
-
-[config]
-# Ensure consistent review language across all PRs
-response_language = "en"
-
-[rag_arguments]
-# Enable RAG context enrichment for codebase duplication compliance checks
-enable_rag = true
-# Include related repositories for comprehensive context
-rag_repo_list = ['onetimesecret/onetimesecret', 'delano/tryouts']
-
-[compliance]
-# Reference custom compliance checklist for project-specific rules
-custom_compliance_path = "pr_compliance_checklist.yaml"
-
-[pr_reviewer]
-# Disable automatic label additions (triggers Claude review workflow noise)
-enable_review_labels_security = false
-enable_review_labels_effort = false
-
-[ignore]
-# Reduce noise by excluding generated files and build artifacts
-glob = [
-    "*.lock",           # Lock files (Gemfile.lock, etc.)
-    "*.gem",            # Built gem files
-    "vendor/**",        # Vendored dependencies
-    "tmp/**",           # Temporary files
-    "log/**",           # Log files
-    "data/**",          # Data directories
-    "public/**",        # Public assets
-    ".yardoc/**",       # YARD documentation cache
-    "dump.rdb",         # Redis database dumps
-    "appendonlydir/**", # Redis append-only file directory
-]

data/pr_compliance_checklist.yaml

@@ -1,45 +0,0 @@
-# Custom Compliance Checklist for Familia
-# Documentation: https://qodo-merge-docs.qodo.ai/tools/compliance/
-
-pr_compliances:
-  - title: "ErrorHandling"
-    compliance_label: true
-    objective: "All external API calls and database operations must have proper error handling"
-    success_criteria: "Try-catch blocks around external calls with appropriate logging or error handling mechanisms"
-    failure_criteria: "External API calls, database operations, or network requests without error handling"
-
-  - title: "TestCoverage"
-    compliance_label: true
-    objective: "New features must include corresponding tests using the Tryouts framework"
-    success_criteria: "Test files present in try/ directory for new functionality following *_try.rb or *.try.rb naming convention"
-    failure_criteria: "New code without test coverage or tests not following Tryouts framework conventions"
-
-  - title: "ChangelogFragment"
-    compliance_label: true
-    objective: "User-facing changes must include a changelog"
-    success_criteria: "New fragment file in changelog.d/ directory following the naming convention and RST format, or updates to CHANGELOG.rst in root directory, or explicit justification for omission"
-    failure_criteria: "User-facing changes without changelog fragment, CHANGELOG.rst updates, or documentation updates"
-
-  - title: "DocumentationUpdates"
-    compliance_label: true
-    objective: "API changes must be reflected in documentation"
-    success_criteria: "YARD documentation comments for new public methods, or updates to docs/ for significant changes"
-    failure_criteria: "New public APIs or significant behavior changes without documentation updates"
-
-  - title: "BackwardCompatibility"
-    compliance_label: true
-    objective: "Changes must maintain backward compatibility or document breaking changes"
-    success_criteria: "No breaking changes to public APIs, or breaking changes clearly documented in migration guides"
-    failure_criteria: "Breaking changes without migration documentation or deprecation warnings"
-
-  - title: "ThreadSafety"
-    compliance_label: true
-    objective: "Code handling shared state must be thread-safe"
-    success_criteria: "Proper synchronization for shared mutable state, or clear documentation of thread-safety assumptions"
-    failure_criteria: "Shared mutable state accessed without synchronization in concurrent contexts"
-
-  - title: "DatabaseKeyNaming"
-    compliance_label: true
-    objective: "Database key generation must follow Familia conventions"
-    success_criteria: "Keys use delim separator, avoid reserved keywords (ttl, db, valkey, redis), and handle empty identifiers"
-    failure_criteria: "Keys using reserved keywords, empty identifiers, or non-standard separators"