familia 2.0.0.pre22 → 2.0.0.pre24

data/lib/familia/features/relationships/participation/through_model_operations.rb

@@ -0,0 +1,150 @@
+# lib/familia/features/relationships/participation/through_model_operations.rb
+#
+# frozen_string_literal: true
+
+module Familia
+  module Features
+    module Relationships
+      module Participation
+        # ThroughModelOperations provides lifecycle management for through models
+        # in participation relationships.
+        #
+        # Through models implement the join table pattern, creating an intermediate
+        # object between target and participant that can carry additional attributes
+        # (e.g., role, permissions, metadata).
+        #
+        # Key characteristics:
+        # - Deterministic identifier: Built from target, participant, and through class
+        # - Auto-lifecycle: Created on add, destroyed on remove
+        # - Idempotent: Re-adding updates existing model
+        # - Atomic: All operations use transactions
+        # - Cache-friendly: Auto-updates updated_at for invalidation
+        #
+        # Example:
+        #   class Membership < Familia::Horreum
+        #     feature :object_identifier
+        #     field :customer_objid
+        #     field :domain_objid
+        #     field :role
+        #     field :updated_at
+        #   end
+        #
+        #   class Domain < Familia::Horreum
+        #     participates_in Customer, :domains, through: :Membership
+        #   end
+        #
+        #   # Through model auto-created with deterministic key
+        #   customer.add_domains_instance(domain, through_attrs: { role: 'admin' })
+        #   # => #<Membership objid="customer:123:domain:456:membership">
+        #
+        module ThroughModelOperations
+          module_function
+
+          # Build a deterministic key for the through model
+          #
+          # The key format ensures uniqueness and allows direct lookup:
+          # {target.prefix}:{target.objid}:{participant.prefix}:{participant.objid}:{through.prefix}
+          #
+          # @param target [Object] The target instance (e.g., customer)
+          # @param participant [Object] The participant instance (e.g., domain)
+          # @param through_class [Class] The through model class
+          # @return [String] Deterministic key for the through model
+          #
+          def build_key(target:, participant:, through_class:)
+            "#{target.class.config_name}:#{target.objid}:" \
+            "#{participant.class.config_name}:#{participant.objid}:" \
+            "#{through_class.config_name}"
+          end
+
+          # Find or create a through model instance
+          #
+          # This method is idempotent - calling it multiple times with the same
+          # target/participant pair will update the existing through model rather
+          # than creating duplicates.
+          #
+          # The through model's updated_at is set on both create and update for
+          # cache invalidation.
+          #
+          # @param through_class [Class] The through model class
+          # @param target [Object] The target instance
+          # @param participant [Object] The participant instance
+          # @param attrs [Hash] Additional attributes to set on through model
+          # @return [Object] The created or updated through model instance
+          #
+          def find_or_create(through_class:, target:, participant:, attrs: {})
+            key = build_key(target: target, participant: participant, through_class: through_class)
+
+            # Try to load existing model - load returns nil if key doesn't exist
+            existing = through_class.load(key)
+
+            # Check if we got a valid loaded object using the public API
+            # This is called outside transaction boundaries (see participant_methods.rb
+            # and target_methods.rb for the transaction boundary documentation)
+            if existing&.exists?
+              # Update existing through model with validated attributes
+              safe_attrs = validated_attrs(through_class, attrs)
+              safe_attrs.each { |k, v| existing.send("#{k}=", v) }
+              existing.updated_at = Familia.now.to_f if existing.respond_to?(:updated_at=)
+              # Save returns boolean, but we want to return the model instance
+              existing.save if safe_attrs.any? || existing.respond_to?(:updated_at=)
+              existing  # Return the model, not the save result
+            else
+              # Create new through model with our deterministic key as objid
+              # Pass objid during initialization to prevent auto-generation
+              inst = through_class.new(objid: key)
+
+              # Set foreign key fields if they exist (validated via respond_to?)
+              target_field = "#{target.class.config_name}_objid"
+              participant_field = "#{participant.class.config_name}_objid"
+              inst.send("#{target_field}=", target.objid) if inst.respond_to?("#{target_field}=")
+              inst.send("#{participant_field}=", participant.objid) if inst.respond_to?("#{participant_field}=")
+
+              # Set updated_at for cache invalidation
+              inst.updated_at = Familia.now.to_f if inst.respond_to?(:updated_at=)
+
+              # Set custom attributes (validated against field schema)
+              safe_attrs = validated_attrs(through_class, attrs)
+              safe_attrs.each { |k, v| inst.send("#{k}=", v) }
+
+              # Save returns boolean, but we want to return the model instance
+              inst.save
+              inst  # Return the model, not the save result
+            end
+          end
+
+          # Find and destroy a through model instance
+          #
+          # Used during remove operations to clean up the join table entry.
+          #
+          # @param through_class [Class] The through model class
+          # @param target [Object] The target instance
+          # @param participant [Object] The participant instance
+          # @return [void]
+          #
+          def find_and_destroy(through_class:, target:, participant:)
+            key = build_key(target: target, participant: participant, through_class: through_class)
+            existing = through_class.load(key)
+            # Use the public exists? method for a more robust check
+            existing&.destroy! if existing&.exists?
+          end
+
+          # Validate attribute keys against the through model's field schema
+          #
+          # This prevents arbitrary method invocation by ensuring only defined
+          # fields can be set via the attrs hash.
+          #
+          # @param through_class [Class] The through model class
+          # @param attrs [Hash] Attributes to validate
+          # @return [Hash] Only attributes whose keys match defined fields
+          #
+          def validated_attrs(through_class, attrs)
+            return {} if attrs.nil? || attrs.empty?
+
+            valid_fields = through_class.fields.map(&:to_sym)
+            attrs.select { |k, _v| valid_fields.include?(k.to_sym) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/familia/features/relationships/participation.rb

@@ -7,6 +7,7 @@ require_relative 'participation_membership'
 require_relative 'collection_operations'
 require_relative 'participation/participant_methods'
 require_relative 'participation/target_methods'
+require_relative 'participation/through_model_operations'
 
 module Familia
   module Features
@@ -117,7 +118,7 @@ module Familia
           # - +ClassName.add_to_collection_name(instance)+ - Add instance to collection
           # - +ClassName.remove_from_collection_name(instance)+ - Remove instance from collection
           #
-          # ==== On Instances (Participant Methods, if bidirectional)
+          # ==== On Instances (Participant Methods, if generate_participant_methods)
           # - +instance.in_class_collection_name?+ - Check membership in class collection
           # - +instance.add_to_class_collection_name+ - Add self to class collection
           # - +instance.remove_from_class_collection_name+ - Remove self from class collection
@@ -134,7 +135,9 @@ module Familia
           #   - +:sorted_set+: Ordered by score (default)
           #   - +:set+: Unordered unique membership
           #   - +:list+: Ordered sequence allowing duplicates
-          # @param bidirectional [Boolean] Whether to generate convenience methods on instances (default: +true+)
+          # @param generate_participant_methods [Boolean] Whether to generate convenience methods on instances (default: +true+)
+          # @param through [Class, Symbol, String, nil] Optional join model class for
+          #        storing additional attributes. See +participates_in+ for details.
           #
           # @example Simple priority-based global collection
           #   class User < Familia::Horreum
@@ -160,7 +163,7 @@ module Familia
           # @see #participates_in for instance-level participation relationships
           # @since 1.0.0
           def class_participates_in(collection_name, score: nil,
-                                    type: :sorted_set, bidirectional: true)
+                                    type: :sorted_set, generate_participant_methods: true, through: nil)
             # Store metadata for this participation relationship
             participation_relationships << ParticipationRelationship.new(
               _original_target: self,   # For class-level, original and resolved are the same
@@ -168,21 +171,23 @@ module Familia
               collection_name: collection_name,
               score: score,
               type: type,
-              bidirectional: bidirectional,
+              generate_participant_methods: generate_participant_methods,
+              through: through,
+              method_prefix: nil,       # Not applicable for class-level participation
             )
 
             # STEP 1: Add collection management methods to the class itself
             # e.g., User.all_users, User.add_to_all_users(user)
             TargetMethods::Builder.build_class_level(self, collection_name, type)
 
-            # STEP 2: Add participation methods to instances (if bidirectional)
+            # STEP 2: Add participation methods to instances (if generate_participant_methods)
             # e.g., user.in_class_all_users?, user.add_to_class_all_users
-            return unless bidirectional
+            return unless generate_participant_methods
 
             # Pass the string 'class' as target to distinguish class-level from instance-level
             # This prevents generating reverse collection methods (user can't have "all_users")
             # See ParticipantMethods::Builder.build for handling of this special case
-            ParticipantMethods::Builder.build(self, 'class', collection_name, type, nil)
+            ParticipantMethods::Builder.build(self, 'class', collection_name, type, nil, through, nil)
           end
 
           # Define an instance-level participation relationship between two classes.
@@ -203,7 +208,7 @@ module Familia
           # - +target.remove_participant_class_name(participant)+ - Remove participant from collection
           # - +target.add_participant_class_names([participants])+ - Bulk add multiple participants
           #
-          # ==== On Participant Class (if bidirectional)
+          # ==== On Participant Class (if generate_participant_methods)
           # - +participant.in_target_collection_name?(target)+ - Check membership in target's collection
           # - +participant.add_to_target_collection_name(target)+ - Add self to target's collection
           # - +participant.remove_from_target_collection_name(target)+ - Remove self from target's collection
@@ -233,12 +238,18 @@ module Familia
           #        different scores (default)
           #   - +:set+: Unordered unique membership
           #   - +:list+: Ordered sequence, allows duplicates
-          # @param bidirectional [Boolean] Whether to generate reverse collection
+          # @param generate_participant_methods [Boolean] Whether to generate reverse collection
           #        methods on participant class. If true, methods are generated using the
           #        name of the target class. (default: +true+)
           # @param as [Symbol, nil] Custom name for reverse collection methods
           #        (e.g., +as: :contracting_orgs+). When provided, overrides the default
           #        method name derived from the target class.
+          # @param through [Class, Symbol, String, nil] Optional join model class for
+          #        storing additional attributes on the relationship. The through model:
+          #   - Must use +feature :object_identifier+
+          #   - Gets auto-created when adding to collection (via +through_attrs:+ param)
+          #   - Gets auto-destroyed when removing from collection
+          #   - Uses deterministic keys: +{target}:{id}:{participant}:{id}:{through}+
           #
           # @example Basic domain-employee relationship
           #
@@ -284,7 +295,7 @@ module Familia
           # @see ModelInstanceMethods#current_participations for membership queries
           # @see ModelInstanceMethods#calculate_participation_score for scoring details
           #
-          def participates_in(target, collection_name, score: nil, type: :sorted_set, bidirectional: true, as: nil)
+          def participates_in(target, collection_name, score: nil, type: :sorted_set, generate_participant_methods: true, as: nil, through: nil, method_prefix: nil)
 
             # Normalize the target class parameter
             target_class = Familia.resolve_class(target)
@@ -306,6 +317,17 @@ module Familia
               ERROR
             end
 
+            # Validate through class if provided
+            if through
+              through_class = Familia.resolve_class(through)
+              raise ArgumentError, "Cannot resolve through class: #{through.inspect}" unless through_class
+
+              unless through_class.respond_to?(:features_enabled) &&
+                     through_class.features_enabled.include?(:object_identifier)
+                raise ArgumentError, "Through model #{through_class} must use `feature :object_identifier`"
+              end
+            end
+
             # Store metadata for this participation relationship
             participation_relationships << ParticipationRelationship.new(
               _original_target: target,      # Original value as passed (Symbol/String/Class)
@@ -313,7 +335,9 @@ module Familia
               collection_name: collection_name,
               score: score,
               type: type,
-              bidirectional: bidirectional,
+              generate_participant_methods: generate_participant_methods,
+              through: through,
+              method_prefix: method_prefix,
             )
 
             # STEP 0: Add participations tracking field to PARTICIPANT class (Domain)
@@ -322,14 +346,14 @@ module Familia
 
             # STEP 1: Add collection management methods to TARGET class (Employee)
             # Employee gets: domains, add_domain, remove_domain, etc.
-            TargetMethods::Builder.build(target_class, collection_name, type)
+            TargetMethods::Builder.build(target_class, collection_name, type, through)
 
             # STEP 2: Add participation methods to PARTICIPANT class (Domain) - only if
-            # bidirectional. e.g. in_employee_domains?, add_to_employee_domains, etc.
-            if bidirectional
+            # generate_participant_methods. e.g. in_employee_domains?, add_to_employee_domains, etc.
+            if generate_participant_methods
               # `as` parameter allows custom naming for reverse collections
               # If not provided, we'll let the builder use the pluralized target class name
-              ParticipantMethods::Builder.build(self, target_class, collection_name, type, as)
+              ParticipantMethods::Builder.build(self, target_class, collection_name, type, as, through, method_prefix)
             end
           end
 

data/lib/familia/features/relationships/participation_relationship.rb

@@ -21,7 +21,9 @@ module Familia
         :collection_name,     # Symbol name of the collection (e.g., :members, :domains)
         :score,               # Proc/Symbol/nil - score calculator for sorted sets
         :type,                # Symbol - collection type (:sorted_set, :set, :list)
-        :bidirectional,       # Boolean/Symbol - whether to generate reverse methods
+        :generate_participant_methods,  # Boolean - whether to generate participant methods
+        :through,             # Symbol/Class/nil - through model class for join table pattern
+        :method_prefix,       # Symbol/nil - custom prefix for reverse method names (e.g., :team)
       ) do
         # Get a unique key for this participation relationship
         # Useful for comparisons and hash keys
@@ -53,6 +55,22 @@ module Familia
           target_class_base == comparison_target_base &&
             collection_name == comparison_collection.to_sym
         end
+
+        # Check if this relationship uses a through model
+        #
+        # @return [Boolean] true if through model is configured
+        def through_model?
+          !through.nil?
+        end
+
+        # Resolve the through class to an actual Class object
+        #
+        # @return [Class, nil] The resolved through class or nil
+        def resolved_through_class
+          return nil unless through
+
+          through.is_a?(Class) ? through : Familia.resolve_class(through)
+        end
       end
     end
   end

data/lib/familia/features/relationships.rb

@@ -38,7 +38,7 @@ module Familia
     #
     #     # Participation with bidirectional control (no method collisions)
     #     participates_in Customer, :domains
-    #     participates_in Team, :domains, bidirectional: false
+    #     participates_in Team, :domains, generate_participant_methods: false
     #     participates_in Organization, :domains, type: :set
     #   end
     #

data/lib/familia/horreum/management.rb

@@ -156,7 +156,10 @@ module Familia
           # doesn't, we return nil. If it does, we proceed to load the object.
           # Otherwise, hgetall will return an empty hash, which will be passed to
           # the constructor, which will then be annoying to debug.
-          return unless does_exist
+          unless does_exist
+            cleanup_stale_instance_entry(objkey)
+            return nil
+          end
         else
           # Optimized mode: Skip existence check
           Familia.debug "[find_by_key] #{self} from key #{objkey} (check_exists: false)"
@@ -166,12 +169,42 @@ module Familia
         obj = dbclient.hgetall(objkey) # horreum objects are persisted as database hashes
         Familia.trace :FIND_BY_DBKEY_INSPECT, nil, "#{objkey}: #{obj.inspect}"
 
-        # If we skipped existence check and got empty hash, key doesn't exist
-        return nil if !check_exists && obj.empty?
+        # Always check for empty hash to handle race conditions where the key
+        # expires between EXISTS check and HGETALL (when check_exists: true),
+        # or simply doesn't exist (when check_exists: false).
+        if obj.empty?
+          cleanup_stale_instance_entry(objkey)
+          return nil
+        end
 
         # Create instance and deserialize fields using shared helper method
         instantiate_from_hash(obj)
       end
+
+      # Removes a stale entry from the instances sorted set.
+      # Called when find_by_dbkey detects that an object no longer exists
+      # (either EXISTS returned false, or HGETALL returned empty hash).
+      #
+      # This provides lazy cleanup of phantom instance entries that can
+      # accumulate when objects expire via TTL without explicit destroy!
+      #
+      # @param objkey [String] The full database key (prefix:identifier:suffix)
+      # @return [void]
+      # @api private
+      def cleanup_stale_instance_entry(objkey)
+        return unless respond_to?(:instances)
+
+        # Key format is prefix:identifier:suffix, so identifier is at index 1
+        parts = Familia.split(objkey)
+        return unless parts.length >= 2
+
+        identifier = parts[1]
+        return if identifier.nil? || identifier.empty?
+
+        instances.remove(identifier)
+        Familia.debug "[find_by_dbkey] Removed stale instance entry: #{identifier}"
+      end
+      private :cleanup_stale_instance_entry
       alias find_by_key find_by_dbkey
 
       # Retrieves and instantiates an object from Database using its identifier.

data/lib/familia/version.rb

@@ -4,5 +4,5 @@
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.0.0.pre22'.freeze unless defined?(Familia::VERSION)
+  VERSION = '2.0.0.pre24'.freeze unless defined?(Familia::VERSION)
 end

data/pr_agent.toml

@@ -9,12 +9,17 @@ response_language = "en"
 # Enable RAG context enrichment for codebase duplication compliance checks
 enable_rag = true
 # Include related repositories for comprehensive context
-rag_repo_list = ['delano/familia', 'delano/tryouts', 'delano/otto']
+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 = [

data/try/edge_cases/find_by_dbkey_race_condition_try.rb

@@ -0,0 +1,248 @@
+# try/edge_cases/find_by_dbkey_race_condition_try.rb
+#
+# frozen_string_literal: true
+
+# Test race condition handling in find_by_dbkey where a key can expire
+# between the EXISTS check and HGETALL retrieval. Also tests lazy cleanup
+# of stale instances entries.
+#
+# The race condition scenario:
+# 1. EXISTS check passes (key exists)
+# 2. Key expires via TTL (or is deleted) before HGETALL
+# 3. HGETALL returns empty hash {}
+# 4. Without fix: instantiate_from_hash({}) creates object with nil identifier
+# 5. With fix: returns nil and cleans up stale instances entry
+
+require_relative '../support/helpers/test_helpers'
+
+RaceConditionUser = Class.new(Familia::Horreum) do
+  identifier_field :user_id
+  field :user_id
+  field :name
+  field :email
+end
+
+RaceConditionSession = Class.new(Familia::Horreum) do
+  identifier_field :session_id
+  field :session_id
+  field :data
+  feature :expiration
+  default_expiration 300
+end
+
+# --- Empty Hash Handling Tests ---
+
+## find_by_dbkey returns nil for empty hash when check_exists: true
+# Simulate race condition: add stale entry to instances, then try to load
+RaceConditionUser.instances.add('stale_user_1', Familia.now)
+initial_count = RaceConditionUser.instances.size
+result = RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('stale_user_1'), check_exists: true)
+result
+#=> nil
+
+## find_by_dbkey returns nil for empty hash when check_exists: false
+RaceConditionUser.instances.add('stale_user_2', Familia.now)
+result = RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('stale_user_2'), check_exists: false)
+result
+#=> nil
+
+## find_by_dbkey handles both check_exists modes consistently for non-existent keys
+result_true = RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('nonexistent_1'), check_exists: true)
+result_false = RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('nonexistent_2'), check_exists: false)
+[result_true, result_false]
+#=> [nil, nil]
+
+# --- Lazy Cleanup Tests ---
+
+## lazy cleanup removes stale entry from instances when loading fails
+RaceConditionUser.instances.clear
+RaceConditionUser.instances.add('phantom_user_1', Familia.now)
+before_count = RaceConditionUser.instances.size
+RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('phantom_user_1'))
+after_count = RaceConditionUser.instances.size
+[before_count, after_count]
+#=> [1, 0]
+
+## lazy cleanup handles multiple stale entries
+RaceConditionUser.instances.clear
+RaceConditionUser.instances.add('phantom_a', Familia.now)
+RaceConditionUser.instances.add('phantom_b', Familia.now)
+RaceConditionUser.instances.add('phantom_c', Familia.now)
+RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('phantom_a'))
+RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('phantom_b'))
+remaining = RaceConditionUser.instances.size
+remaining
+#=> 1
+
+## lazy cleanup only removes the specific stale entry
+RaceConditionUser.instances.clear
+real_user = RaceConditionUser.new(user_id: 'real_user_1', name: 'Real', email: 'real@example.com')
+real_user.save
+RaceConditionUser.instances.add('phantom_mixed', Familia.now)
+before = RaceConditionUser.instances.members.sort
+RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('phantom_mixed'))
+after = RaceConditionUser.instances.members.sort
+real_user.destroy!
+[before.include?('phantom_mixed'), before.include?('real_user_1'), after.include?('phantom_mixed'), after.include?('real_user_1')]
+#=> [true, true, false, true]
+
+# --- Race Condition Simulation Tests ---
+
+## simulated race: key deleted between conceptual EXISTS and actual load
+# This simulates what happens when a key expires between EXISTS and HGETALL
+user = RaceConditionUser.new(user_id: 'race_user_1', name: 'Race', email: 'race@example.com')
+user.save
+dbkey = RaceConditionUser.dbkey('race_user_1')
+
+# Verify key exists
+exists_before = Familia.dbclient.exists(dbkey).positive?
+
+# Simulate TTL expiration by directly deleting the key but leaving instances entry
+Familia.dbclient.del(dbkey)
+
+# Now find_by_dbkey should return nil and clean up instances
+result = RaceConditionUser.find_by_dbkey(dbkey)
+exists_after = RaceConditionUser.instances.members.include?('race_user_1')
+[exists_before, result, exists_after]
+#=> [true, nil, false]
+
+## simulated race with check_exists: false also handles cleanup
+user2 = RaceConditionUser.new(user_id: 'race_user_2', name: 'Race2', email: 'race2@example.com')
+user2.save
+dbkey2 = RaceConditionUser.dbkey('race_user_2')
+
+# Delete key but leave instances entry
+Familia.dbclient.del(dbkey2)
+
+result = RaceConditionUser.find_by_dbkey(dbkey2, check_exists: false)
+cleaned = !RaceConditionUser.instances.members.include?('race_user_2')
+[result, cleaned]
+#=> [nil, true]
+
+# --- TTL Expiration Tests ---
+
+## TTL expiration leaves stale instances entry (demonstrating the problem)
+session = RaceConditionSession.new(session_id: 'ttl_session_1', data: 'test data')
+session.save
+session.expire(1) # 1 second TTL
+
+# Verify it's in instances
+in_instances_before = RaceConditionSession.instances.members.include?('ttl_session_1')
+
+# Wait for TTL to expire
+sleep(1.5)
+
+# Key is gone but instances entry remains (this is the stale entry problem)
+key_exists = Familia.dbclient.exists(RaceConditionSession.dbkey('ttl_session_1')).positive?
+in_instances_still = RaceConditionSession.instances.members.include?('ttl_session_1')
+[in_instances_before, key_exists, in_instances_still]
+#=> [true, false, true]
+
+## lazy cleanup fixes stale entry after TTL expiration
+# Now when we try to load, it should clean up the stale entry
+result = RaceConditionSession.find_by_dbkey(RaceConditionSession.dbkey('ttl_session_1'))
+in_instances_after = RaceConditionSession.instances.members.include?('ttl_session_1')
+[result, in_instances_after]
+#=> [nil, false]
+
+## find methods clean up stale entries after TTL expiration
+session2 = RaceConditionSession.new(session_id: 'ttl_session_2', data: 'test data 2')
+session2.save
+session2.expire(1)
+sleep(1.5)
+
+# Use find_by_id (which calls find_by_dbkey internally)
+result = RaceConditionSession.find_by_id('ttl_session_2')
+cleaned = !RaceConditionSession.instances.members.include?('ttl_session_2')
+[result, cleaned]
+#=> [nil, true]
+
+# --- Count Consistency Tests ---
+
+## count reflects reality after lazy cleanup
+RaceConditionUser.instances.clear
+# Create real user
+real = RaceConditionUser.new(user_id: 'count_real', name: 'Real', email: 'real@example.com')
+real.save
+
+# Add phantom entries
+RaceConditionUser.instances.add('count_phantom_1', Familia.now)
+RaceConditionUser.instances.add('count_phantom_2', Familia.now)
+
+count_before = RaceConditionUser.count
+
+# Trigger lazy cleanup by attempting to load phantoms
+RaceConditionUser.find_by_id('count_phantom_1')
+RaceConditionUser.find_by_id('count_phantom_2')
+
+count_after = RaceConditionUser.count
+real.destroy!
+[count_before, count_after]
+#=> [3, 1]
+
+## keys_count vs count after lazy cleanup
+RaceConditionUser.instances.clear
+real2 = RaceConditionUser.new(user_id: 'keys_count_real', name: 'Real', email: 'real@example.com')
+real2.save
+RaceConditionUser.instances.add('keys_count_phantom', Familia.now)
+
+# Before cleanup: count includes phantom, keys_count doesn't
+count_before = RaceConditionUser.count
+keys_count_before = RaceConditionUser.keys_count
+
+# Trigger lazy cleanup
+RaceConditionUser.find_by_id('keys_count_phantom')
+
+# After cleanup: both should match
+count_after = RaceConditionUser.count
+keys_count_after = RaceConditionUser.keys_count
+
+real2.destroy!
+[count_before, keys_count_before, count_after, keys_count_after]
+#=> [2, 1, 1, 1]
+
+# --- Edge Cases ---
+
+## empty identifier in key doesn't cause issues
+# Key format with empty identifier would be "prefix::suffix"
+# This shouldn't happen in practice, but we handle it gracefully
+malformed_key = "#{RaceConditionUser.prefix}::object"
+result = RaceConditionUser.find_by_dbkey(malformed_key)
+result
+#=> nil
+
+## key with unusual identifier characters
+RaceConditionUser.instances.add('user:with:colons', Familia.now)
+result = RaceConditionUser.find_by_dbkey(RaceConditionUser.dbkey('user:with:colons'))
+# Should return nil (key doesn't exist) and attempt cleanup
+# Note: cleanup may not work perfectly for identifiers with delimiters
+result
+#=> nil
+
+## concurrent load attempts on same stale entry
+RaceConditionUser.instances.clear
+RaceConditionUser.instances.add('concurrent_phantom', Familia.now)
+
+threads = []
+results = []
+mutex = Mutex.new
+
+5.times do
+  threads << Thread.new do
+    r = RaceConditionUser.find_by_id('concurrent_phantom')
+    mutex.synchronize { results << r }
+  end
+end
+
+threads.each(&:join)
+
+# All should return nil, and instances should be cleaned
+all_nil = results.all?(&:nil?)
+cleaned = !RaceConditionUser.instances.members.include?('concurrent_phantom')
+[all_nil, cleaned, results.size]
+#=> [true, true, 5]
+
+# --- Cleanup ---
+
+RaceConditionUser.instances.clear
+RaceConditionSession.instances.clear