familia 2.0.0.pre21 → 2.0.0.pre22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 07042bac6b1c1cb48aa4110964f76fcb1bd030b5814d09077e71458528982fc4
-  data.tar.gz: 1cc64f41698963091108f48f45a8af7be8e77473aacae2ccd734175be84f2a45
+  metadata.gz: cf37d5963fa9ae33323b70ad4eea48cfa45e91aa59ea46ecce2ac85644a9d0e2
+  data.tar.gz: 8880f7e2914b12db9a0cdcf2f741968c7c43731ef15833a921be72df19de70cd
 SHA512:
-  metadata.gz: 4c2a76ca3e47aff299fcb51ac56fa8b3c6701135921a99228cefe8eb770a8455b0b237849fbd85cb60b8e6bb3d436abe20d7afc384acc6e0e8e7f2ad3ba05d65
-  data.tar.gz: 1c3a6b8ccb9479d701eb98f4b00d700c1e05978d29b0247ce83937471c3ab7a8df515ba1b387ceaf1dc7cfd56f7a8cdabee0b6038093eb5595c69babb6670a27
+  metadata.gz: 31b585405895213ee9857a66306ee2e7b60ce2f26568915571bc8c992e1169ff8589856c40253e2b8ef8081fd3805b0f32f0a769d85108a11528786621ac4440
+  data.tar.gz: 715766983ba9c44603bc8a94c240dc716130cc70cc182fd84dec1cc5b17333de32e52b1677610d62b6aba047aadada2cdf65b61867df1d3bffab08f94d8c4067

data/.talismanrc

@@ -5,5 +5,9 @@
 # https://thoughtworks.github.io/talisman/docs/configuring-talisman/severity-threshold/
 #
 threshold: medium
-fileignoreconfig: []
+fileignoreconfig:
+  - filename: try/features/external_identifier/external_identifier_try.rb
+    checksum: dcc0dd135cd8c569b096c922e6260e446d25b65b7b97b8a4cb4ccaac59325b38
+  - filename: try/features/object_identifier/object_identifier_try.rb
+    checksum: 10c94f802b2fa3a39fa33bf7dc34dac2ecaa2dd453ff97a19313f96a32fadeff
 version: ""

data/CHANGELOG.rst

@@ -7,6 +7,49 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.0.0.pre22:
+
+2.0.0.pre22 — 2025-12-03
+========================
+
+- **ExternalIdentifier Format Flexibility**: The `external_identifier` feature now supports customizable format templates via the `format` option (e.g., `format: 'cust_%{id}'` or `format: 'api-%{id}'`). Default format remains `'ext_%{id}'`. Provides complete flexibility for various ID formatting needs including different prefixes, separators, URL paths, or no prefix at all.
+
+- **Participation Relationships with Symbol/String Target Classes**: Fixed four bugs that occurred when calling `participates_in` with Symbol/String target class instead of Class object. Issues included NoMethodError during relationship definition (private method call), failures in `current_participations` (undefined `familia_name`), errors in `target_class_config_name` (undefined `config_name`), and confusing error messages for load order issues. All now properly resolve using `Familia.resolve_class` API with clear error messages for common issues.
+
+- **Pipelined Bulk Loading Methods**: New `load_multi` and `load_multi_by_keys` methods enable efficient bulk object loading using Redis pipelining, reducing network round trips from N×2 commands to a single batch (up to 2× performance improvement). Methods maintain nil-return contract for missing objects and preserve input order.
+
+- **Optional EXISTS Check Optimization**: The `find_by_dbkey` and `find_by_identifier` methods now accept `check_exists:` parameter (default: `true`) to optionally skip EXISTS check, reducing Redis commands from 2 to 1 per object. Maintains backwards compatibility and same nil-return behavior.
+
+- **Parameter Consistency**: The `suffix` parameter in `find_by_identifier` is now a keyword parameter (was optional positional) for consistency with `check_exists`, following Ruby conventions.
+
+Added
+-----
+
+- Bidirectional reverse collection methods for ``participates_in`` with ``_instances`` suffix (e.g., ``user.project_team_instances``, ``user.project_team_ids``). Supports union behavior for multiple collections and custom naming via ``as:`` parameter. Closes #179.
+
+Changed
+-------
+
+- All Ruby files now include consistent headers with ``frozen_string_literal: true`` pragma for improved performance and memory efficiency. Headers follow the format: filename comment, blank comment line, frozen string literal pragma. Executable scripts properly place shebang first.
+
+- Standardized DataType serialization to use JSON encoding for type preservation, matching Horreum field behavior. All primitive values (Integer, Boolean, String, Float, Hash, Array, nil) are now consistently serialized through JSON, ensuring types are preserved across the Redis storage boundary. Familia object references continue to use identifier extraction. Issue #190.
+
+Fixed
+-----
+
+- Fixed critical race condition in mutex initialization for connection chain lazy loading. The mutex itself was being lazily initialized with ``||=``, which is not atomic and could result in multiple threads creating different mutex instances, defeating synchronization. Changed to eager initialization via ``Connection.included`` hook. (`lib/familia/horreum/connection.rb`)
+
+- Fixed critical race condition in mutex initialization for logger lazy loading. Similar to connection chain issue, the logger mutex was lazily initialized with ``||=``. Changed to eager initialization at module definition time. (`lib/familia/logging.rb`)
+
+- Fixed logger assignment atomicity issue where ``Familia.logger=`` set ``DatabaseLogger.logger`` outside the mutex synchronization block, potentially causing ``Familia.logger`` and ``DatabaseLogger.logger`` to be temporarily out of sync during concurrent access. Moved ``DatabaseLogger.logger`` assignment inside the synchronization block. (`lib/familia/logging.rb`)
+
+- Added explicit return statement to ``Familia.logger`` method for robustness against future refactoring. (`lib/familia/logging.rb`)
+
+AI Assistance
+-------------
+
+- Claude Code (Opus 4, Sonnet 4.5): Implementation of bidirectional participation relationships, external identifier format flexibility, bulk loading optimization with pipelining, race condition fixes in mutex initialization, frozen string literal pragma automation (308 files), and DataType serialization standardization. Comprehensive test coverage and documentation throughout.
+
 .. _changelog-2.0.0.pre21:
 
 2.0.0.pre21 — 2025-10-21

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre21)
+    familia (2.0.0.pre22)
       benchmark (~> 0.4)
       concurrent-ruby (~> 1.3)
       connection_pool (~> 2.5)

data/lib/familia/connection/operation_core.rb

@@ -87,8 +87,7 @@ module Familia
 
         # Return MultiResult format for consistency
         results = proxy.collected_results
-        summary_boolean = results.all? { |ret| !ret.is_a?(Exception) }
-        MultiResult.new(summary_boolean, results)
+        MultiResult.new(results)
       end
     end
   end

data/lib/familia/connection/pipelined_core.rb

@@ -80,9 +80,7 @@ module Familia
         end
 
         # Return same MultiResult format as other methods
-        # Pipeline success is true if no exceptions occurred (all commands executed)
-        summary_boolean = command_return_values.none? { |ret| ret.is_a?(Exception) }
-        MultiResult.new(summary_boolean, command_return_values)
+        MultiResult.new(command_return_values)
       end
     end
   end

data/lib/familia/connection/transaction_core.rb

@@ -158,8 +158,7 @@ module Familia
         end
 
         # Return same MultiResult format as other methods
-        summary_boolean = command_return_values.all? { |ret| %w[OK 0 1].include?(ret.to_s) }
-        MultiResult.new(summary_boolean, command_return_values)
+        MultiResult.new(command_return_values)
       end
     end
   end

data/lib/familia/data_type/serialization.rb

@@ -8,46 +8,45 @@ module Familia
       # Serializes a value for storage in the database.
       #
       # @param val [Object] The value to be serialized.
-      # @param strict_values [Boolean] Whether to enforce strict value
-      #   serialization (default: true).
-      # @return [String, nil] The serialized representation of the value, or nil
-      #   if serialization fails.
+      # @return [String] The JSON-serialized representation of the value.
       #
-      # @note When a class option is specified, it uses Familia.identifier_extractor
-      #   to extract the identifier from objects. Otherwise, it extracts identifiers
-      #   from Familia::Base instances or class names.
+      # Serialization priority:
+      # 1. Familia objects (Base instances or classes) → extract identifier
+      # 2. All other values → JSON serialize for type preservation
       #
-      # @example With a class option
-      #   serialize_value(User.new(name: "Cloe"), strict_values: false) #=> '{"name":"Cloe"}'
+      # This unifies behavior with Horreum fields (Issue #190), ensuring
+      # consistent type preservation across DataType and Horreum.
       #
-      # @example Without a class option
-      #   serialize_value(123) #=> "123"
-      #   serialize_value("hello") #=> "hello"
+      # @example Familia object reference
+      #   serialize_value(customer_obj) #=> "customer_123" (identifier)
       #
-      # @raise [Familia::NotDistinguishableError] If serialization fails under strict
-      #   mode.
+      # @example Primitive values (JSON encoded)
+      #   serialize_value(42)          #=> "42"
+      #   serialize_value("hello")     #=> '"hello"'
+      #   serialize_value(true)        #=> "true"
+      #   serialize_value(nil)         #=> "null"
+      #   serialize_value([1, 2, 3])   #=> "[1,2,3]"
       #
-      def serialize_value(val, strict_values: true)
-        prepared = nil
-
+      def serialize_value(val)
         Familia.trace :TOREDIS, nil, "#{val}<#{val.class}|#{opts[:class]}>" if Familia.debug?
 
-        if opts[:class]
-          prepared = Familia.identifier_extractor(opts[:class])
-          Familia.debug "  from opts[class] <#{opts[:class]}>: #{prepared || '<nil>'}"
+        # Priority 1: Handle Familia object references - extract identifier
+        # This preserves the existing behavior for storing object references
+        if val.is_a?(Familia::Base) || (val.is_a?(Class) && val.ancestors.include?(Familia::Base))
+          prepared = val.is_a?(Class) ? val.name : val.identifier
+          Familia.debug "  Familia object: #{val.class} => #{prepared}"
+          return prepared
         end
 
-        if prepared.nil?
-          # Enforce strict values when no class option is specified
-          prepared = Familia.identifier_extractor(val)
-          Familia.debug "  from <#{val.class}> => <#{prepared.class}>"
-        end
+        # Priority 2: Everything else gets JSON serialized for type preservation
+        # This unifies behavior with Horreum fields (Issue #190)
+        prepared = Familia::JsonSerializer.dump(val)
+        Familia.debug "  JSON serialized: #{val.class} => #{prepared}"
 
         if Familia.debug?
-          Familia.trace :TOREDIS, nil, "#{val}<#{val.class}|#{opts[:class]}> => #{prepared}<#{prepared.class}>"
+          Familia.trace :TOREDIS, nil, "#{val}<#{val.class}> => #{prepared}<#{prepared.class}>"
         end
 
-        Familia.warn "[#{self.class}#serialize_value] nil returned for #{opts[:class]}##{name}" if prepared.nil?
         prepared
       end
 
@@ -81,27 +80,41 @@ module Familia
       def deserialize_values_with_nil(*values)
         Familia.debug "deserialize_values: (#{@opts}) #{values}"
         return [] if values.empty?
-        return values.flatten unless @opts[:class]
 
-        unless @opts[:class].respond_to?(load_method)
-          raise Familia::Problem, "No such method: #{@opts[:class]}##{load_method}"
-        end
+        # If a class option is specified, use class-based deserialization
+        if @opts[:class]
+          unless @opts[:class].respond_to?(load_method)
+            raise Familia::Problem, "No such method: #{@opts[:class]}##{load_method}"
+          end
 
-        values.collect! do |obj|
-          next if obj.nil?
+          values.collect! do |obj|
+            next if obj.nil?
 
-          val = @opts[:class].send load_method, obj
-          Familia.debug "[#{self.class}#deserialize_values] nil returned for #{@opts[:class]}##{name}" if val.nil?
+            val = @opts[:class].send load_method, obj
+            Familia.debug "[#{self.class}#deserialize_values] nil returned for #{@opts[:class]}##{name}" if val.nil?
 
-          val
-        rescue StandardError => e
-          Familia.info val
-          Familia.info "Parse error for #{dbkey} (#{load_method}): #{e.message}"
-          Familia.info e.backtrace
-          nil
+            val
+          rescue StandardError => e
+            Familia.info val
+            Familia.info "Parse error for #{dbkey} (#{load_method}): #{e.message}"
+            Familia.info e.backtrace
+            nil
+          end
+
+          return values
         end
 
-        values
+        # No class option: JSON deserialize each value for type preservation (Issue #190)
+        values.flatten.collect do |obj|
+          next if obj.nil?
+
+          begin
+            Familia::JsonSerializer.parse(obj)
+          rescue Familia::SerializerError
+            # Fallback for legacy data stored without JSON encoding
+            obj
+          end
+        end
       end
 
       # Deserializes a single value from the database.
@@ -110,13 +123,15 @@ module Familia
       # @return [Object, nil] The deserialized object, the default value if
       #   val is nil, or nil if deserialization fails.
       #
-      # @note If no class option is specified, the original value is
-      #   returned unchanged.
+      # Deserialization priority:
+      # 1. Redis::Future objects → return as-is (transaction handling)
+      # 2. nil values → return default option value
+      # 3. Class option specified → use class-based deserialization
+      # 4. No class option → JSON parse for type preservation
       #
-      # NOTE: Currently only the DataType class uses this method. Horreum
-      # fields are a newer addition and don't support the full range of
-      # deserialization options that DataType supports. It uses serialize_value
-      # for serialization since everything becomes a string in Valkey.
+      # This unifies behavior with Horreum fields (Issue #190), ensuring
+      # consistent type preservation. Legacy data stored without JSON
+      # encoding is returned as-is.
       #
       def deserialize_value(val)
         # Handle Redis::Future objects during transactions first
@@ -124,10 +139,20 @@ module Familia
 
         return @opts[:default] if val.nil?
 
-        return val unless @opts[:class]
+        # If a class option is specified, use the existing class-based deserialization
+        if @opts[:class]
+          ret = deserialize_values val
+          return ret&.first # return the object or nil
+        end
 
-        ret = deserialize_values val
-        ret&.first # return the object or nil
+        # No class option: JSON deserialize for type preservation (Issue #190)
+        # This unifies behavior with Horreum fields
+        begin
+          Familia::JsonSerializer.parse(val)
+        rescue Familia::SerializerError
+          # Fallback for legacy data stored without JSON encoding
+          val
+        end
       end
     end
   end

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

@@ -129,7 +129,7 @@ module Familia
     alias add_element add
 
     def score(val)
-      ret = dbclient.zscore dbkey, serialize_value(val, strict_values: false)
+      ret = dbclient.zscore dbkey, serialize_value(val)
       ret&.to_f
     end
     alias [] score
@@ -142,13 +142,13 @@ module Familia
 
     # rank of member +v+ when ordered lowest to highest (starts at 0)
     def rank(v)
-      ret = dbclient.zrank dbkey, serialize_value(v, strict_values: false)
+      ret = dbclient.zrank dbkey, serialize_value(v)
       ret&.to_i
     end
 
     # rank of member +v+ when ordered highest to lowest (starts at 0)
     def revrank(v)
-      ret = dbclient.zrevrank dbkey, serialize_value(v, strict_values: false)
+      ret = dbclient.zrevrank dbkey, serialize_value(v)
       ret&.to_i
     end
 
@@ -269,7 +269,7 @@ module Familia
     end
 
     def increment(val, by = 1)
-      dbclient.zincrby(dbkey, by, val).to_i
+      dbclient.zincrby(dbkey, by, serialize_value(val)).to_i
     end
     alias incr increment
     alias incrby increment
@@ -285,12 +285,7 @@ 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?
-      # We use `strict_values: false` here to allow for the deletion of values
-      # that are in the sorted set. If it's a horreum object, the value is
-      # the identifier and not a serialized version of the object. So either
-      # the value exists in the sorted set or it doesn't -- we don't need to
-      # raise an error if it's not found.
-      dbclient.zrem dbkey, serialize_value(value, strict_values: false)
+      dbclient.zrem dbkey, serialize_value(value)
     end
     alias remove remove_element # deprecated
 

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

@@ -6,6 +6,28 @@ module Familia
   class StringKey < DataType
     def init; end
 
+    # StringKey uses raw string serialization (not JSON) because Redis string
+    # operations like INCR, DECR, APPEND operate on raw values.
+    # This overrides the base JSON serialization from DataType.
+    def serialize_value(val)
+      Familia.trace :TOREDIS, nil, "#{val}<#{val.class}>" if Familia.debug?
+
+      # Handle Familia object references - extract identifier
+      if val.is_a?(Familia::Base) || (val.is_a?(Class) && val.ancestors.include?(Familia::Base))
+        return val.is_a?(Class) ? val.name : val.identifier
+      end
+
+      # StringKey uses raw string conversion for Redis compatibility
+      val.to_s
+    end
+
+    # StringKey returns raw values (not JSON parsed)
+    def deserialize_value(val)
+      return val if val.is_a?(Redis::Future)
+      return @opts[:default] if val.nil?
+      val
+    end
+
     # Returns the number of elements in the list
     # @return [Integer] number of elements
     def char_count

data/lib/familia/features/external_identifier.rb

@@ -176,6 +176,35 @@ module Familia
           # extid_lookup.remove_field(extid)
           nil
         end
+
+        # Check if a string matches the extid format for the Horreum class. The specific
+        # class is important b/c each one can have its own custom prefix, like `ext_`.
+        #
+        # The validator accepts a reasonable range of ID lengths (20-32 characters) to
+        # accommodate potential changes to the entropy or encoding while maintaining
+        # security. The current implementation generates exactly 25 base36 characters
+        # from 16 bytes (128 bits), but this flexibility allows for future adjustments
+        # without breaking validation.
+        #
+        # @param guess [String] The string to check
+        # @return [Boolean] true if the guess matches the extid format, false otherwise
+        def extid?(guess)
+          return false if guess.to_s.empty?
+
+          options = feature_options(:external_identifier)
+          format = options[:format] || 'ext_%{id}'
+
+          # Extract prefix and suffix from format
+          return false unless format.include?('%{id}')
+          prefix, suffix = format.split('%{id}', 2)
+
+          # Build regex pattern to match the extid format
+          # Accept 20-32 base36 characters to allow for entropy/encoding variations
+          # Current generation: 16 bytes -> base36 -> 25 chars (rjust with '0')
+          pattern = /\A#{Regexp.escape(prefix)}[0-9a-z]{20,32}#{Regexp.escape(suffix)}\z/i
+
+          !!(guess =~ pattern)
+        end
       end
 
       # Instance methods for external identifier management

data/lib/familia/features/object_identifier.rb

@@ -279,6 +279,53 @@ module Familia
           # objid_lookup.remove_field(objid)
           nil
         end
+
+        # Check if a string matches the objid format for the Horreum class. The specific
+        # class is important b/c each one can have its own type of objid generator.
+        #
+        # @param guess [String] The string to check
+        # @return [Boolean] true if the guess matches the objid format, false otherwise
+        def objid?(guess)
+          return false if guess.to_s.empty?
+
+          options = feature_options(:object_identifier)
+          generator = options[:generator] || DEFAULT_GENERATOR
+
+          case generator
+          when :uuid_v7, :uuid_v4
+            # UUID format: xxxxxxxx-xxxx-Vxxx-xxxx-xxxxxxxxxxxx (36 chars with hyphens)
+            # Validate structure and that all characters are valid hex digits
+            guess_str = guess.to_s
+            return false unless guess_str.length == 36
+            return false unless guess_str[8] == '-' && guess_str[13] == '-' && guess_str[18] == '-' && guess_str[23] == '-'
+
+            # Extract segments and validate each is valid hex
+            segments = guess_str.split('-')
+            return false unless segments.length == 5
+            return false unless segments[0] =~ /\A[0-9a-fA-F]{8}\z/  # 8 hex chars
+            return false unless segments[1] =~ /\A[0-9a-fA-F]{4}\z/  # 4 hex chars
+            return false unless segments[2] =~ /\A[0-9a-fA-F]{4}\z/  # 4 hex chars (includes version)
+            return false unless segments[3] =~ /\A[0-9a-fA-F]{4}\z/  # 4 hex chars
+            return false unless segments[4] =~ /\A[0-9a-fA-F]{12}\z/ # 12 hex chars
+
+            # Validate version character
+            version_char = guess_str[14]
+            if generator == :uuid_v7
+              version_char == '7'
+            else # generator == :uuid_v4
+              version_char == '4'
+            end
+          when :hex
+            # Hex format: pure hexadecimal without hyphens
+            !!(guess =~ /\A[0-9a-fA-F]+\z/)
+          when Proc
+            # Cannot determine format for custom Proc generators
+            Familia.warn "[objid?] Validation not supported for custom Proc generators on #{name}" if Familia.debug?
+            false
+          else
+            false
+          end
+        end
       end
 
       # Instance methods for object identifier management

data/lib/familia/features/relationships/indexing/rebuild_strategies.rb

@@ -76,7 +76,7 @@ module Familia
           #     batch_size: 100
           #   ) { |p| puts "#{p[:completed]}/#{p[:total]} (#{p[:rate]}/s)" }
           #
-          def rebuild_via_instances(indexed_class, field, add_method, batch_size: 100, &progress)
+          def rebuild_via_instances(indexed_class, field, add_method, index_hashkey, batch_size: 100, &progress)
             unless indexed_class.respond_to?(:instances)
               raise ArgumentError, "#{indexed_class.name} does not have an instances collection"
             end
@@ -104,8 +104,8 @@ module Familia
             processed = 0
             indexed_count = 0
 
-            # Process in batches - use membersraw to get raw identifiers without deserialization
-            instances.membersraw.each_slice(batch_size) do |identifiers|
+            # Process in batches - use members to get deserialized identifiers
+            instances.members.each_slice(batch_size) do |identifiers|
               # Bulk load objects, filtering out nils (deleted/missing objects)
               objects = indexed_class.load_multi(identifiers).compact
 
@@ -117,8 +117,8 @@ module Familia
                   # Skip nil/empty field values gracefully
                   next unless value && !value.to_s.strip.empty?
 
-                  # For class-level indexes, use HSET directly into temp key
-                  tx.hset(temp_key, value.to_s, obj.identifier.to_s)
+                  # For class-level indexes, use HSET with serialized value for consistency
+                  tx.hset(temp_key, value.to_s, index_hashkey.serialize_value(obj))
                   batch_indexed += 1
                 end
               end
@@ -177,7 +177,7 @@ module Familia
           #     batch_size: 100
           #   )
           #
-          def rebuild_via_participation(scope_instance, indexed_class, field, add_method, collection, cardinality, batch_size: 100, &progress)
+          def rebuild_via_participation(scope_instance, indexed_class, field, add_method, collection, cardinality, index_hashkey, batch_size: 100, &progress)
             total = collection.size
             start_time = Familia.now
 
@@ -222,8 +222,8 @@ module Familia
             processed = 0
             indexed_count = 0
 
-            # Process in batches - use membersraw to get raw identifiers
-            collection.membersraw.each_slice(batch_size) do |identifiers|
+            # Process in batches - use members to get deserialized identifiers
+            collection.members.each_slice(batch_size) do |identifiers|
               objects = indexed_class.load_multi(identifiers).compact
 
               # Transaction per batch
@@ -233,9 +233,9 @@ module Familia
                   value = obj.send(field)
                   next unless value && !value.to_s.strip.empty?
 
-                  # For unique index: HSET temp_key field_value identifier
+                  # For unique index: HSET temp_key field_value serialized_identifier
                   # For multi-index: SADD temp_key:field_value identifier
-                  tx.hset(temp_key, value.to_s, obj.identifier.to_s)
+                  tx.hset(temp_key, value.to_s, index_hashkey.serialize_value(obj))
                   batch_indexed += 1
                 end
               end
@@ -295,7 +295,7 @@ module Familia
           #     batch_size: 100
           #   )
           #
-          def rebuild_via_scan(indexed_class, field, add_method, scope_instance: nil, batch_size: 100, &progress)
+          def rebuild_via_scan(indexed_class, field, add_method, index_hashkey, scope_instance: nil, batch_size: 100, &progress)
             start_time = Familia.now
 
             # Build key pattern for SCAN
@@ -342,7 +342,7 @@ module Familia
 
               # Process in batches
               if batch.size >= batch_size
-                batch_indexed = RebuildStrategies.process_scan_batch(batch, indexed_class, field, temp_key, scope_instance)
+                batch_indexed = RebuildStrategies.process_scan_batch(batch, indexed_class, field, temp_key, index_hashkey, scope_instance)
                 processed += batch.size
                 indexed_count += batch_indexed
 
@@ -362,7 +362,7 @@ module Familia
 
             # Process remaining batch
             unless batch.empty?
-              batch_indexed = RebuildStrategies.process_scan_batch(batch, indexed_class, field, temp_key, scope_instance)
+              batch_indexed = RebuildStrategies.process_scan_batch(batch, indexed_class, field, temp_key, index_hashkey, scope_instance)
               processed += batch.size
               indexed_count += batch_indexed
             end
@@ -385,7 +385,7 @@ module Familia
           # @param scope_instance [Object, nil] Optional scope instance. If provided, only objects belonging to this scope will be indexed.
           # @return [Integer] Number of objects indexed in this batch
           #
-          def process_scan_batch(keys, indexed_class, field, temp_key, scope_instance)
+          def process_scan_batch(keys, indexed_class, field, temp_key, index_hashkey, scope_instance)
             # Load objects by keys
             objects = indexed_class.load_multi_by_keys(keys).compact
 
@@ -411,7 +411,7 @@ module Familia
                 value = obj.send(field)
                 next unless value && !value.to_s.strip.empty?
 
-                tx.hset(temp_key, value.to_s, obj.identifier.to_s)
+                tx.hset(temp_key, value.to_s, index_hashkey.serialize_value(obj))
                 batch_indexed += 1
               end
             end

data/lib/familia/features/relationships/indexing/unique_index_generators.rb

@@ -191,6 +191,7 @@ module Familia
                   index_config = indexed_class.indexing_relationships.find { |rel| rel.index_name == index_name }
 
                   # Strategy 2: Use participation-based rebuild
+                  index_hashkey = send(index_name)  # Get the index HashKey for serialization
                   Familia::Features::Relationships::Indexing::RebuildStrategies.rebuild_via_participation(
                     self,                                      # scope_instance (e.g., company)
                     indexed_class,                             # e.g., Employee
@@ -198,15 +199,18 @@ module Familia
                     :"add_to_#{scope_class_config}_#{index_name}",  # e.g., :add_to_company_badge_index
                     collection,
                     index_config.cardinality,                  # :unique or :multi
+                    index_hashkey,                             # Pass index for serialization
                     batch_size: batch_size,
                     &progress_block
                   )
                 else
                   # Strategy 3: Fall back to SCAN with filtering
+                  index_hashkey = send(index_name)  # Get the index HashKey for serialization
                   Familia::Features::Relationships::Indexing::RebuildStrategies.rebuild_via_scan(
                     indexed_class,
                     field,
                     :"add_to_#{scope_class_config}_#{index_name}",
+                    index_hashkey,                             # Pass index for serialization
                     scope_instance: self,
                     batch_size: batch_size,
                     &progress_block
@@ -373,19 +377,23 @@ module Familia
             indexed_class.define_singleton_method(:"rebuild_#{index_name}") do |batch_size: 100, &progress_block|
               if respond_to?(:instances)
                 # Strategy 1: Use instances collection (fastest)
+                index_hashkey = send(index_name)  # Get the index HashKey for serialization
                 Familia::Features::Relationships::Indexing::RebuildStrategies.rebuild_via_instances(
                   self,                                 # indexed_class (e.g., User)
                   field,                                # e.g., :email
                   :"add_to_class_#{index_name}",       # e.g., :add_to_class_email_lookup
+                  index_hashkey,                        # Pass index for serialization
                   batch_size: batch_size,
                   &progress_block
                 )
               else
                 # Strategy 3: Fall back to SCAN
+                index_hashkey = send(index_name)  # Get the index HashKey for serialization
                 Familia::Features::Relationships::Indexing::RebuildStrategies.rebuild_via_scan(
                   self,
                   field,
                   :"add_to_class_#{index_name}",
+                  index_hashkey,                        # Pass index for serialization
                   batch_size: batch_size,
                   &progress_block
                 )

data/lib/familia/horreum/database_commands.rb

@@ -263,15 +263,20 @@ module Familia
       #
       #   | Scenario | Use | Why |
       #   |----------|-----|-----|
-      #   | Check if exists, then create | WATCH | Must prevent duplicate creation |
+      #   | First-one-wins / idempotency | SET NX | Atomic claim, no read needed |
+      #   | Distributed lock acquisition | SET NX EX | Claim with automatic expiry |
       #   | Read value, update conditionally | WATCH | Decision depends on current state |
       #   | Compare-and-swap operations | WATCH | Need optimistic locking |
       #   | Version-based updates | WATCH | Must detect concurrent changes |
+      #   | Status transitions (pending→processing) | WATCH | Must verify current state |
       #   | Batch field updates | MULTI only | No conditional logic |
       #   | Increment + timestamp together | MULTI only | Concurrent increments OK |
       #   | Save object atomically | MULTI only | Just need atomicity |
       #   | Update indexes with save | MULTI only | No state checking needed |
       #
+      #    If you don't need to read before deciding, WATCH adds complexity
+      #    without benefit. SET NX handles the "claim" pattern in one atomic shot.
+      #
       # @param suffix_override [String, nil] Optional suffix override
       # @return [String] 'OK' on success
       def watch(...)