familia 2.0.0.pre19 → 2.0.0.pre22

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

@@ -0,0 +1,69 @@
+# lib/familia/features/relationships/participation_membership.rb
+#
+# frozen_string_literal: true
+
+module Familia
+  module Features
+    module Relationships
+      #
+      # ParticipationMembership
+      #
+      # Represents runtime snapshot of a participant's membership in a target collection.
+      # Returned by current_participations to provide a type-safe, structured view
+      # of actual participation state.
+      #
+      # @note This represents what currently exists in Redis, not just configuration.
+      #   See ParticipationRelationship for static configuration metadata.
+      #
+      # @example
+      #   membership = user.current_participations.first
+      #   membership.target_class  # => "Team"
+      #   membership.target_id     # => "team123"
+      #   membership.collection_name  # => :members
+      #   membership.type          # => :sorted_set
+      #   membership.score         # => 1762554020.05
+      #
+      ParticipationMembership = Data.define(
+        :target_class,      # String - class name (e.g., "Customer")
+        :target_id,         # String - target instance identifier
+        :collection_name,   # Symbol - collection name (e.g., :domains)
+        :type,              # Symbol - collection type (:sorted_set, :set, :list)
+        :score,             # Float - optional, for sorted_set only
+        :decoded_score,     # Hash - optional, decoded score data
+        :position           # Integer - optional, for list only
+      ) do
+        # Check if this membership is a sorted set
+        # @return [Boolean]
+        def sorted_set?
+          type == :sorted_set
+        end
+
+        # Check if this membership is a set
+        # @return [Boolean]
+        def set?
+          type == :set
+        end
+
+        # Check if this membership is a list
+        # @return [Boolean]
+        def list?
+          type == :list
+        end
+
+        # Get the target instance (requires loading from database)
+        # @return [Familia::Horreum, nil] the loaded target instance
+        def target_instance
+          return nil unless target_class
+
+          # Resolve class from string name
+          # Only rescue NameError (class doesn't exist), not all exceptions
+          klass = Object.const_get(target_class)
+          klass.find_by_id(target_id)
+        rescue NameError
+          # Target class doesn't exist or isn't loaded
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -1,4 +1,6 @@
 # lib/familia/features/relationships/participation_relationship.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Features
@@ -10,20 +12,46 @@ module Familia
       # Used to configure code generation and runtime behavior for participates_in
       # and class_participates_in declarations.
       #
+      # @note target_class is resolved once at definition time for performance.
+      #   Use _original_target for debugging/introspection to see what was passed.
+      #
       ParticipationRelationship = Data.define(
-        :target_class,        # Class object that owns the collection
+        :_original_target,    # Original Symbol/String/Class as passed to participates_in
+        :target_class,        # Resolved Class object (e.g., User class, not :User symbol)
         :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 - whether to generate reverse methods
+        :bidirectional,       # Boolean/Symbol - whether to generate reverse methods
       ) do
+        # Get a unique key for this participation relationship
+        # Useful for comparisons and hash keys
         #
-        # Get the normalized config name for the target class
+        # @return [String] unique identifier in format "TargetClass:collection_name"
+        def unique_key
+          Familia.join(target_class_base, collection_name)
+        end
+
+        # Get the base class name without namespace
+        # Handles anonymous class wrappers like "#<Class:0x123>::SymbolResolutionCustomer"
         #
-        # @return [String] The config name (e.g., "user", "perf_test_customer")
+        # @return [String] base class name (e.g., "Customer")
+        def target_class_base
+          target_class.name.split('::').last
+        end
+
+        # Check if this relationship matches the given target and collection
+        # Handles namespace-agnostic class comparison
         #
-        def target_class_config_name
-          target_class.config_name
+        # @param comparison_target [Class, String, Symbol] target to compare against
+        # @param comparison_collection [Symbol, String] collection name to compare
+        # @return [Boolean] true if both target and collection match
+        def matches?(comparison_target, comparison_collection)
+          # Normalize comparison target to base class name
+          comparison_target = comparison_target.name if comparison_target.is_a?(Class)
+          comparison_target_base = comparison_target.to_s.split('::').last
+
+          target_class_base == comparison_target_base &&
+            collection_name == comparison_collection.to_sym
         end
       end
     end

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

@@ -1,4 +1,6 @@
 # lib/familia/features/relationships/score_encoding.rb
+#
+# frozen_string_literal: true
 
 module Familia
   module Features

data/lib/familia/features/relationships.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/relationships.rb
+#
+# frozen_string_literal: true
 
 require 'securerandom'
 require_relative 'relationships/score_encoding'
@@ -84,7 +86,7 @@ module Familia
 
       # Feature initialization
       def self.included(base)
-        Familia.ld "[#{base}] Relationships included"
+        Familia.debug "[#{base}] Relationships included"
         base.extend ModelClassMethods
         base.include ModelInstanceMethods
 
@@ -157,7 +159,7 @@ module Familia
         def create_temp_key(base_name, ttl = 300)
           timestamp = Familia.now.to_i
           random_suffix = SecureRandom.hex(3)
-          temp_key = "temp:#{base_name}:#{timestamp}:#{random_suffix}"
+          temp_key = Familia.join('temp', base_name, timestamp, random_suffix)
 
           # UnsortedSet immediate expiry to ensure cleanup even if operation fails
           if respond_to?(:dbclient)
@@ -256,7 +258,7 @@ module Familia
         def create_temp_key(base_name, ttl = 300)
           timestamp = Familia.now.to_i
           random_suffix = SecureRandom.hex(3)
-          temp_key = "temp:#{base_name}:#{timestamp}:#{random_suffix}"
+          temp_key = Familia.join('temp', base_name, timestamp, random_suffix)
 
           # UnsortedSet immediate expiry to ensure cleanup even if operation fails
           dbclient.expire(temp_key, ttl)

data/lib/familia/features/safe_dump.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/safe_dump.rb
+#
+# frozen_string_literal: true
 
 #
 # Class instance variables are used here for configuration. These are set

data/lib/familia/features/transient_fields/redacted_string.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/transient_fields/redacted_string.rb
+#
+# frozen_string_literal: true
 
 # RedactedString
 #

data/lib/familia/features/transient_fields/single_use_redacted_string.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/transient_fields/single_use_redacted_string.rb
+#
+# frozen_string_literal: true
 
 require_relative 'redacted_string'
 

data/lib/familia/features/transient_fields/transient_field_type.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/transient_fields/transient_field_type.rb
+#
+# frozen_string_literal: true
 
 require 'familia/field_type'
 
@@ -80,7 +82,7 @@ module Familia
     #
     def define_fast_writer(_klass)
       # No fast writer for transient fields since they're not persisted
-      Familia.ld "[TransientFieldType] Skipping fast writer for transient field: #{@name}"
+      Familia.debug "[TransientFieldType] Skipping fast writer for transient field: #{@name}"
       nil
     end
 
@@ -117,7 +119,7 @@ module Familia
     #
     def serialize(_value, _record = nil)
       # Transient fields should never be serialized
-      Familia.ld "[TransientFieldType] WARNING: serialize called on transient field #{@name}"
+      Familia.debug "[TransientFieldType] WARNING: serialize called on transient field #{@name}"
       nil
     end
 
@@ -132,7 +134,7 @@ module Familia
     #
     def deserialize(_value, _record = nil)
       # Transient fields should never be deserialized
-      Familia.ld "[TransientFieldType] WARNING: deserialize called on transient field #{@name}"
+      Familia.debug "[TransientFieldType] WARNING: deserialize called on transient field #{@name}"
       nil
     end
   end

data/lib/familia/features/transient_fields.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/transient_fields.rb
+#
+# frozen_string_literal: true
 
 require_relative 'transient_fields/redacted_string'
 require_relative 'transient_fields/transient_field_type'

data/lib/familia/features.rb

@@ -1,4 +1,6 @@
 # lib/familia/features.rb
+#
+# frozen_string_literal: true
 
 # Load the Autoloader first, then use it to load all other features
 require_relative 'features/autoloader'

data/lib/familia/field_type.rb

@@ -1,4 +1,6 @@
 # lib/familia/field_type.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # Base class for all field types in Familia
@@ -152,7 +154,7 @@ module Familia
 
             # Convert value for database storage
             prepared = serialize_value(val)
-            Familia.ld "[FieldType#define_fast_writer] #{fast_method_name} val: #{val.class} prepared: #{prepared.class}"
+            Familia.debug "[FieldType#define_fast_writer] #{fast_method_name} val: #{val.class} prepared: #{prepared.class}"
 
             # Use the setter method to update instance variable
             send(:"#{method_name}=", val) if method_name

data/lib/familia/horreum/connection.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum/connection.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class Horreum
@@ -24,10 +26,19 @@ module Familia
       # 2. DefaultConnectionHandler - Horreum model class-level @dbclient
       # 3. GlobalFallbackHandler - Familia.dbclient(uri || logical_database) (global fallback)
       #
+      # Thread-safe lazy initialization using double-checked locking to ensure
+      # only a single connection chain is built even under high concurrent load.
+      #
       # @return [Redis] the Database connection instance.
       #
       def dbclient(uri = nil)
-        @class_connection_chain ||= build_connection_chain
+        # Fast path: return existing chain if already initialized
+        return @class_connection_chain.handle(uri) if @class_connection_chain
+
+        # Slow path: thread-safe initialization
+        @class_connection_chain_mutex.synchronize do
+          @class_connection_chain ||= build_connection_chain
+        end
         @class_connection_chain.handle(uri)
       end
 
@@ -268,6 +279,11 @@ module Familia
           .add_handler(@cached_connection_handler)
           .add_handler(@create_connection_handler)
       end
+
+      # Thread-safe mutex initialization when module is extended
+      def self.extended(base)
+        base.instance_variable_set(:@class_connection_chain_mutex, Mutex.new)
+      end
     end
   end
 end

data/lib/familia/horreum/database_commands.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum/database_commands.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # Familia::Horreum
@@ -261,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(...)

data/lib/familia/horreum/definition.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum/definition.rb
+#
+# frozen_string_literal: true
 
 require_relative 'settings'
 
@@ -98,7 +100,7 @@ module Familia
             @current_field_group = nil
           end
         else
-          Familia.ld "[field_group] Created field group :#{name} but no block given" if Familia.debug?
+          Familia.debug "[field_group] Created field group :#{name} but no block given"
         end
 
         field_groups[name.to_sym]
@@ -124,7 +126,10 @@ module Familia
       #   ]
       #
       def field_groups
-        @field_groups ||= {}
+        @field_groups_mutex ||= Familia::ThreadSafety::InstrumentedMutex.new('field_groups')
+        @field_groups || @field_groups_mutex.synchronize do
+          @field_groups ||= {}
+        end
       end
 
       # Sets or retrieves the unique identifier field for the class.
@@ -215,8 +220,10 @@ module Familia
       # Returns the list of field names defined for the class in the order
       # that they were defined. i.e. `field :a; field :b; fields => [:a, :b]`.
       def fields
-        @fields ||= []
-        @fields
+        @fields_mutex ||= Familia::ThreadSafety::InstrumentedMutex.new('fields')
+        @fields || @fields_mutex.synchronize do
+          @fields ||= []
+        end
       end
 
       def class_related_fields
@@ -235,7 +242,10 @@ module Familia
 
       # Storage for field type instances
       def field_types
-        @field_types ||= {}
+        @field_types_mutex ||= Familia::ThreadSafety::InstrumentedMutex.new('field_types')
+        @field_types || @field_types_mutex.synchronize do
+          @field_types ||= {}
+        end
       end
 
       # Returns a hash mapping field names to method names for backward compatibility
@@ -476,7 +486,7 @@ module Familia
 
               # Convert the provided value to a format suitable for Database storage.
               prepared = serialize_value(val)
-              Familia.ld "[define_fast_writer_method] #{fast_method_name} val: #{val.class} prepared: #{prepared.class}"
+              Familia.debug "[define_fast_writer_method] #{fast_method_name} val: #{val.class} prepared: #{prepared.class}"
 
               # Use the existing accessor method to set the attribute value.
               send :"#{method_name}=", val