familia 2.0.0.pre18 → 2.0.0.pre21

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

@@ -1,5 +1,9 @@
+# lib/familia/features/relationships/indexing/unique_index_generators.rb
+#
 # frozen_string_literal: true
 
+require_relative 'rebuild_strategies'
+
 module Familia
   module Features
     module Relationships
@@ -49,11 +53,11 @@ module Familia
           # @param indexed_class [Class] The class being indexed (e.g., Employee)
           # @param field [Symbol] The field to index
           # @param index_name [Symbol] Name of the index
-          # @param within [Class, Symbol, nil] Parent class for instance-scoped index
+          # @param within [Class, Symbol, nil] Scope class for instance-scoped index
           # @param query [Boolean] Whether to generate query methods
           def setup(indexed_class:, field:, index_name:, within:, query:)
             # Normalize parameters and determine scope type
-            target_class, scope_type = if within
+            scope_class, scope_type = if within
               k = Familia.resolve_class(within)
               [k, :instance]
             else
@@ -63,7 +67,8 @@ module Familia
             # Store metadata for this indexing relationship
             indexed_class.indexing_relationships << IndexingRelationship.new(
               field:             field,
-              target_class:      target_class,
+              scope_class:       scope_class,
+              within:            within,
               index_name:        index_name,
               query:             query,
               cardinality:       :unique,
@@ -73,10 +78,10 @@ module Familia
             case scope_type
             when :instance
               # Instance-scoped index (within: Company)
-              if query && target_class.is_a?(Class)
-                generate_query_methods_destination(indexed_class, field, target_class, index_name)
+              if query && scope_class.is_a?(Class)
+                generate_query_methods_destination(indexed_class, field, scope_class, index_name)
               end
-              generate_mutation_methods_self(indexed_class, field, target_class, index_name)
+              generate_mutation_methods_self(indexed_class, field, scope_class, index_name)
             when :class
               # Class-level index (no within:)
               indexed_class.send(:ensure_index_field, indexed_class, index_name, :class_hashkey)
@@ -85,7 +90,8 @@ module Familia
             end
           end
 
-          # Generates query methods ON THE PARENT CLASS (Company when within: Company):
+          # Generates query methods ON THE SCOPE CLASS (Company when within: Company)
+          #
           # - company.find_by_badge_number(badge) - find by field value
           # - company.find_all_by_badge_number([badges]) - batch lookup
           # - company.badge_index - DataType accessor
@@ -93,17 +99,20 @@ module Familia
           #
           # @param indexed_class [Class] The class being indexed (e.g., Employee)
           # @param field [Symbol] The field to index (e.g., :badge_number)
-          # @param target_class [Class] The parent class (e.g., Company)
+          # @param scope_class [Class] The scope class providing uniqueness context (e.g., Company)
           # @param index_name [Symbol] Name of the index (e.g., :badge_index)
-          def generate_query_methods_destination(indexed_class, field, target_class, index_name)
-            # Resolve target class using Familia pattern
-            actual_target_class = Familia.resolve_class(target_class)
+          def generate_query_methods_destination(indexed_class, field, scope_class, index_name)
+            # Resolve scope class using Familia pattern
+            actual_scope_class = Familia.resolve_class(scope_class)
 
             # Ensure the index field is declared (creates accessor that returns DataType)
-            actual_target_class.send(:ensure_index_field, actual_target_class, index_name, :hashkey)
+            actual_scope_class.send(:ensure_index_field, actual_scope_class, index_name, :hashkey)
+
+            # Get scope_class_config for method naming (needed for rebuild methods)
+            scope_class_config = actual_scope_class.config_name
 
             # Generate instance query method (e.g., company.find_by_badge_number)
-            actual_target_class.class_eval do
+            actual_scope_class.class_eval do
               define_method(:"find_by_#{field}") do |provided_value|
                 # Use declared field accessor instead of manual instantiation
                 index_hash = send(index_name)
@@ -121,7 +130,10 @@ module Familia
 
               # Generate bulk query method (e.g., company.find_all_by_badge_number)
               define_method(:"find_all_by_#{field}") do |provided_ids|
-                provided_ids = Array(provided_ids)
+                # Convert to array and filter nil inputs before querying Redis.
+                # This prevents wasteful lookups for empty string keys (nil.to_s → "").
+                # Output may contain fewer elements than input (standard ORM behavior).
+                provided_ids = Array(provided_ids).compact
                 return [] if provided_ids.empty?
 
                 # Use declared field accessor instead of manual instantiation
@@ -129,7 +141,8 @@ module Familia
 
                 # Get all identifiers from the hash
                 record_ids = index_hash.values_at(*provided_ids.map(&:to_s))
-                # Filter out nil values and instantiate objects
+
+                # Filter out nil values (non-existent records) and instantiate objects
                 record_ids.compact.map { |record_id|
                   indexed_class.find_by_identifier(record_id)
                 }
@@ -139,77 +152,166 @@ module Familia
               # No need to manually define it here
 
               # Generate method to rebuild the unique index for this parent instance
-              define_method(:"rebuild_#{index_name}") do
-                # Use declared field accessor instead of manual instantiation
-                index_hash = send(index_name)
+              define_method(:"rebuild_#{index_name}") do |batch_size: 100, &progress_block|
+                # Find the collection containing the indexed class.
+                #
+                # Strategy 1: Check if indexed_class has a participation relationship
+                # pointing back to this scope class. Participation relationships are
+                # stored on the PARTICIPANT class (indexed_class), not the target.
+                #
+                # Example: When RebuildTestEmployee.participates_in(RebuildTestCompany, :employees),
+                # the relationship is stored on RebuildTestEmployee, and we need to find it
+                # by matching target_class (RebuildTestCompany) with self.class.
+                collection = nil
+                if indexed_class.respond_to?(:participation_relationships)
+                  participation = indexed_class.participation_relationships.find do |rel|
+                    rel.target_class == self.class
+                  end
+
+                  if participation
+                    collection = send(participation.collection_name)
+                  end
+                end
 
-                # Clear existing index using DataType method
-                index_hash.clear
+                # Strategy 2: Fallback to checking related_fields for explicit class: option
+                unless collection
+                  if self.class.respond_to?(:related_fields)
+                    self.class.related_fields&.each do |name, field_def|
+                      # Check if this DataType's class option matches the indexed class
+                      if field_def.opts[:class] == indexed_class
+                        collection = send(name)
+                        break
+                      end
+                    end
+                  end
+                end
 
-                # Rebuild from all existing objects
-                # This would need to scan through all objects belonging to this parent
-                # Implementation depends on how objects are stored/tracked
+                if collection
+                  # Find the IndexingRelationship to get cardinality metadata
+                  index_config = indexed_class.indexing_relationships.find { |rel| rel.index_name == index_name }
+
+                  # Strategy 2: Use participation-based rebuild
+                  Familia::Features::Relationships::Indexing::RebuildStrategies.rebuild_via_participation(
+                    self,                                      # scope_instance (e.g., company)
+                    indexed_class,                             # e.g., Employee
+                    field,                                     # e.g., :badge_number
+                    :"add_to_#{scope_class_config}_#{index_name}",  # e.g., :add_to_company_badge_index
+                    collection,
+                    index_config.cardinality,                  # :unique or :multi
+                    batch_size: batch_size,
+                    &progress_block
+                  )
+                else
+                  # Strategy 3: Fall back to SCAN with filtering
+                  Familia::Features::Relationships::Indexing::RebuildStrategies.rebuild_via_scan(
+                    indexed_class,
+                    field,
+                    :"add_to_#{scope_class_config}_#{index_name}",
+                    scope_instance: self,
+                    batch_size: batch_size,
+                    &progress_block
+                  )
+                end
               end
             end
           end
 
-          # Generates mutation methods ON THE INDEXED CLASS (Employee):
-          # Instance methods for parent-scoped unique index operations:
-          # - employee.add_to_company_badge_index(company)
+          # Generates mutation methods ON THE INDEXED CLASS (Employee)
+          #
+          # Instance methods for scope-scoped unique index operations:
+          # - employee.add_to_company_badge_index(company) - automatically validates uniqueness
           # - employee.remove_from_company_badge_index(company)
           # - employee.update_in_company_badge_index(company, old_badge)
+          # - employee.guard_unique_company_badge_index!(company) - manual validation
           #
           # @param indexed_class [Class] The class being indexed (e.g., Employee)
           # @param field [Symbol] The field to index (e.g., :badge_number)
-          # @param target_class [Class] The parent class (e.g., Company)
+          # @param scope_class [Class] The scope class providing uniqueness context (e.g., Company)
           # @param index_name [Symbol] Name of the index (e.g., :badge_index)
-          def generate_mutation_methods_self(indexed_class, field, target_class, index_name)
-            target_class_config = target_class.config_name
+          def generate_mutation_methods_self(indexed_class, field, scope_class, index_name)
+            scope_class_config = scope_class.config_name
             indexed_class.class_eval do
-              method_name = :"add_to_#{target_class_config}_#{index_name}"
-              Familia.ld("[UniqueIndexGenerators] #{name} method #{method_name}")
+              method_name = :"add_to_#{scope_class_config}_#{index_name}"
+              Familia.debug("[UniqueIndexGenerators] #{name} method #{method_name}")
 
-              define_method(method_name) do |target_instance|
-                return unless target_instance
+              define_method(method_name) do |scope_instance|
+                return unless scope_instance
 
                 field_value = send(field)
                 return unless field_value
 
-                # Use declared field accessor on target instance
-                index_hash = target_instance.send(index_name)
+                # Automatically validate uniqueness before adding to index.
+                # Skip validation inside transactions since guard methods require read
+                # operations not available in MULTI/EXEC blocks.
+                unless Fiber[:familia_transaction]
+                  guard_method = :"guard_unique_#{scope_class_config}_#{index_name}!"
+                  send(guard_method, scope_instance) if respond_to?(guard_method)
+                end
+
+                # Use declared field accessor on scope instance
+                index_hash = scope_instance.send(index_name)
 
-                # Use HashKey DataType method
+                # Set the value (guard already validated uniqueness)
                 index_hash[field_value.to_s] = identifier
               end
 
-              method_name = :"remove_from_#{target_class_config}_#{index_name}"
-              Familia.ld("[UniqueIndexGenerators] #{name} method #{method_name}")
+              # Add a guard method to enforce unique constraint on this instance-scoped index
+              #
+              # @param scope_instance [Object] The scope instance providing uniqueness context (e.g., a Company)
+              # @raise [Familia::RecordExistsError] if a record with the same field value
+              #   exists in the scope's index. Values are compared as strings.
+              # @return [void]
+              #
+              # @example
+              #   employee.guard_unique_company_badge_index!(company)
+              #
+              method_name = :"guard_unique_#{scope_class_config}_#{index_name}!"
+              Familia.debug("[UniqueIndexGenerators] #{name} method #{method_name}")
+
+              define_method(method_name) do |scope_instance|
+                return unless scope_instance
 
-              define_method(method_name) do |target_instance|
-                return unless target_instance
+                field_value = send(field)
+                return unless field_value
+
+                # Use declared field accessor on scope instance
+                index_hash = scope_instance.send(index_name)
+                existing_id = index_hash.get(field_value.to_s)
+
+                if existing_id && existing_id != identifier
+                  raise Familia::RecordExistsError,
+                    "#{self.class} exists in #{scope_instance.class} with #{field}=#{field_value}"
+                end
+              end
+
+              method_name = :"remove_from_#{scope_class_config}_#{index_name}"
+              Familia.debug("[UniqueIndexGenerators] #{name} method #{method_name}")
+
+              define_method(method_name) do |scope_instance|
+                return unless scope_instance
 
                 field_value = send(field)
                 return unless field_value
 
-                # Use declared field accessor on target instance
-                index_hash = target_instance.send(index_name)
+                # Use declared field accessor on scope instance
+                index_hash = scope_instance.send(index_name)
 
                 # Remove using HashKey DataType method
                 index_hash.remove(field_value.to_s)
               end
 
-              method_name = :"update_in_#{target_class_config}_#{index_name}"
-              Familia.ld("[UniqueIndexGenerators] #{name} method #{method_name}")
+              method_name = :"update_in_#{scope_class_config}_#{index_name}"
+              Familia.debug("[UniqueIndexGenerators] #{name} method #{method_name}")
 
-              define_method(method_name) do |target_instance, old_field_value = nil|
-                return unless target_instance
+              define_method(method_name) do |scope_instance, old_field_value = nil|
+                return unless scope_instance
 
                 new_field_value = send(field)
 
                 # Use Familia's transaction method for atomicity with DataType abstraction
-                target_instance.transaction do |_tx|
-                  # Use declared field accessor on target instance
-                  index_hash = target_instance.send(index_name)
+                scope_instance.transaction do |_tx|
+                  # Use declared field accessor on scope instance
+                  index_hash = scope_instance.send(index_name)
 
                   # Remove old value if provided
                   index_hash.remove(old_field_value.to_s) if old_field_value
@@ -228,10 +330,12 @@ module Familia
           # - Employee.email_index
           # - Employee.rebuild_email_index
           def generate_query_methods_class(field, index_name, indexed_class)
+            # Generate class-level single record method
             indexed_class.define_singleton_method(:"find_by_#{field}") do |provided_id|
-              index_hash = send(index_name) # Access the class-level hashkey DataType
+              index_hash = send(index_name) # access the class-level hashkey DataType
 
-              # Get the identifier from the hash using .get method.
+              # Get the identifier from the db hashkey using .get method.
+              #
               # We use .get instead of [] because it's part of the standard interface
               # common across all DataType classes (List, UnsortedSet, SortedSet, HashKey).
               # While unique indexes always use HashKey, using .get maintains consistency
@@ -245,12 +349,18 @@ module Familia
 
             # Generate class-level bulk query method
             indexed_class.define_singleton_method(:"find_all_by_#{field}") do |provided_ids|
-              provided_ids = Array(provided_ids)
+              # Convert to array and filter nil inputs before querying Redis.
+              # This prevents wasteful lookups for empty string keys (nil.to_s → "").
+              # Output may contain fewer elements than input (standard ORM behavior).
+              provided_ids = Array(provided_ids).compact
               return [] if provided_ids.empty?
 
-              index_hash = send(index_name) # Access the class-level hashkey DataType
+              index_hash = send(index_name) # access the class-level hashkey DataType
+
+              # Get multiple identifiers from the db hashkey using .values_at
               record_ids = index_hash.values_at(*provided_ids.map(&:to_s))
-              # Filter out nil values and instantiate objects
+
+              # Filter out nil values (non-existent records) and instantiate objects
               record_ids.compact.map { |record_id|
                 indexed_class.find_by_identifier(record_id)
               }
@@ -260,15 +370,26 @@ module Familia
             # No need to manually create it - Horreum handles this automatically
 
             # Generate method to rebuild the class-level index
-            indexed_class.define_singleton_method(:"rebuild_#{index_name}") do
-              index_hash = send(index_name) # Access the class-level hashkey DataType
-
-              # Clear existing index using DataType method
-              index_hash.clear
-
-              # Rebuild from all existing objects
-              # This would need to scan through all objects of this class
-              # Implementation depends on how objects are stored/tracked
+            indexed_class.define_singleton_method(:"rebuild_#{index_name}") do |batch_size: 100, &progress_block|
+              if respond_to?(:instances)
+                # Strategy 1: Use instances collection (fastest)
+                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
+                  batch_size: batch_size,
+                  &progress_block
+                )
+              else
+                # Strategy 3: Fall back to SCAN
+                Familia::Features::Relationships::Indexing::RebuildStrategies.rebuild_via_scan(
+                  self,
+                  field,
+                  :"add_to_class_#{index_name}",
+                  batch_size: batch_size,
+                  &progress_block
+                )
+              end
             end
           end
 
@@ -285,9 +406,28 @@ module Familia
 
                 return unless field_value
 
+                # Just set the value - uniqueness should be validated before save
                 index_hash[field_value.to_s] = identifier
               end
 
+              # Add a guard method to enforce unique constraint on this specific index
+              #
+              # @raise [Familia::RecordExistsError] if a record with the same
+              # field value exists. Values are compared as strings.
+              #
+              # @return [void]
+              define_method(:"guard_unique_#{index_name}!") do
+                field_value = send(field)
+                return unless field_value
+
+                index_hash = self.class.send(index_name)
+                existing_id = index_hash.get(field_value.to_s)
+
+                if existing_id && existing_id != identifier
+                  raise Familia::RecordExistsError, "#{self.class} exists #{field}=#{field_value}"
+                end
+              end
+
               define_method(:"remove_from_class_#{index_name}") do
                 index_hash = self.class.send(index_name)  # Access the class-level hashkey DataType
                 field_value = send(field)

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

@@ -1,8 +1,11 @@
 # lib/familia/features/relationships/indexing.rb
+#
+# frozen_string_literal: true
 
 require_relative 'indexing_relationship'
 require_relative 'indexing/multi_index_generators'
 require_relative 'indexing/unique_index_generators'
+require_relative 'indexing/rebuild_strategies'
 
 module Familia
   module Features
@@ -50,7 +53,7 @@ module Familia
       # Terminology:
       # - unique_index: 1:1 field-to-object mapping (HashKey)
       # - multi_index: 1:many field-to-objects mapping (UnsortedSet, no scores)
-      # - within: parent class for instance-scoped indexes
+      # - within: scope class providing uniqueness boundary for instance-scoped indexes
       # - query: whether to generate find_by_* methods (default: true)
       #
       # Key Patterns:
@@ -89,7 +92,7 @@ module Familia
           #
           # @param field [Symbol] The field to index on
           # @param index_name [Symbol] Name of the index
-          # @param within [Class, Symbol] The parent class that owns the index
+          # @param within [Class, Symbol] The scope class providing uniqueness context
           # @param query [Boolean] Whether to generate query methods
           #
           # @example Instance-scoped multi-value indexing
@@ -109,7 +112,7 @@ module Familia
           #
           # @param field [Symbol] The field to index on
           # @param index_name [Symbol] Name of the index hash
-          # @param within [Class, Symbol] Optional parent class for instance-scoped unique index
+          # @param within [Class, Symbol] Optional scope class for instance-scoped unique index
           # @param query [Boolean] Whether to generate query methods
           #
           # @example Class-level unique index
@@ -136,70 +139,68 @@ module Familia
 
           # Ensure proper DataType field is declared for index
           # Similar to ensure_collection_field in participation system
-          def ensure_index_field(target_class, index_name, field_type)
-            return if target_class.method_defined?(index_name) || target_class.respond_to?(index_name)
+          def ensure_index_field(scope_class, index_name, field_type)
+            return if scope_class.method_defined?(index_name) || scope_class.respond_to?(index_name)
 
-            target_class.send(field_type, index_name)
+            scope_class.send(field_type, index_name)
           end
         end
 
         # Instance methods for indexed objects
         module ModelInstanceMethods
-          # Update all indexes for a given parent context
-          # For class-level indexes (class_indexed_by), parent_context should be nil
-          # For relationship indexes (indexed_by), parent_context should be the parent instance
-          def update_all_indexes(old_values = {}, parent_context = nil)
+          # Update all indexes for a given scope context
+          # For class-level indexes (unique_index without within:), scope_context should be nil
+          # For instance-scoped indexes (with within:), scope_context should be the scope instance
+          def update_all_indexes(old_values = {}, scope_context = nil)
             return unless self.class.respond_to?(:indexing_relationships)
 
             self.class.indexing_relationships.each do |config|
               field = config.field
               index_name = config.index_name
-              target_class = config.target_class
               old_field_value = old_values[field]
 
               # Determine which update method to call
-              if target_class == self.class
+              if config.within.nil?
                 # Class-level index (unique_index without within:)
                 send("update_in_class_#{index_name}", old_field_value)
               else
-                # Relationship index (unique_index or multi_index with within:) - requires parent context
-                next unless parent_context
+                # Instance-scoped index (unique_index or multi_index with within:) - requires scope context
+                next unless scope_context
 
                 # Use config_name for method naming
-                target_class_config = Familia.resolve_class(config.target_class).config_name
-                send("update_in_#{target_class_config}_#{index_name}", parent_context, old_field_value)
+                scope_class_config = Familia.resolve_class(config.scope_class).config_name
+                send("update_in_#{scope_class_config}_#{index_name}", scope_context, old_field_value)
               end
             end
           end
 
-          # Remove from all indexes for a given parent context
-          # For class-level indexes (class_indexed_by), parent_context should be nil
-          # For relationship indexes (indexed_by), parent_context should be the parent instance
-          def remove_from_all_indexes(parent_context = nil)
+          # Remove from all indexes for a given scope context
+          # For class-level indexes (unique_index without within:), scope_context should be nil
+          # For instance-scoped indexes (with within:), scope_context should be the scope instance
+          def remove_from_all_indexes(scope_context = nil)
             return unless self.class.respond_to?(:indexing_relationships)
 
             self.class.indexing_relationships.each do |config|
               index_name = config.index_name
-              target_class = config.target_class
 
               # Determine which remove method to call
-              if target_class == self.class
+              if config.within.nil?
                 # Class-level index (unique_index without within:)
                 send("remove_from_class_#{index_name}")
               else
-                # Relationship index (unique_index or multi_index with within:) - requires parent context
-                next unless parent_context
+                # Instance-scoped index (unique_index or multi_index with within:) - requires scope context
+                next unless scope_context
 
                 # Use config_name for method naming
-                target_class_config = Familia.resolve_class(config.target_class).config_name
-                send("remove_from_#{target_class_config}_#{index_name}", parent_context)
+                scope_class_config = Familia.resolve_class(config.scope_class).config_name
+                send("remove_from_#{scope_class_config}_#{index_name}", scope_context)
               end
             end
           end
 
           # Get all indexes this object appears in
-          # Note: For target-scoped indexes, this only shows class-level indexes
-          # since target-scoped indexes require a specific target instance
+          # Note: For instance-scoped indexes, this only shows class-level indexes
+          # since instance-scoped indexes require a specific scope instance
           #
           # @return [Array<Hash>] Array of index information
           def current_indexings
@@ -210,19 +211,18 @@ module Familia
             self.class.indexing_relationships.each do |config|
               field = config.field
               index_name = config.index_name
-              target_class = config.target_class
               cardinality = config.cardinality
               field_value = send(field)
 
               next unless field_value
 
-              if target_class == self.class
+              if config.within.nil?
                 # Class-level index (unique_index without within:) - check hash key using DataType
                 index_hash = self.class.send(index_name)
                 next unless index_hash.key?(field_value.to_s)
 
                 memberships << {
-                  target_class: 'class',
+                  scope_class: 'class',
                   index_name: index_name,
                   field: field,
                   field_value: field_value,
@@ -231,17 +231,17 @@ module Familia
                   type: 'unique_index',
                 }
               else
-                # Instance-scoped index (unique_index or multi_index with within:) - cannot check without target instance
-                # This would require scanning all possible target instances
+                # Instance-scoped index (unique_index or multi_index with within:) - cannot check without scope instance
+                # This would require scanning all possible scope instances
                 memberships << {
-                  target_class: config.target_class_config_name,
+                  scope_class: config.scope_class_config_name,
                   index_name: index_name,
                   field: field,
                   field_value: field_value,
-                  index_key: 'target_dependent',
+                  index_key: 'scope_dependent',
                   cardinality: cardinality,
                   type: cardinality == :unique ? 'unique_index' : 'multi_index',
-                  note: 'Requires target instance for verification',
+                  note: 'Requires scope instance for verification',
                 }
               end
             end
@@ -249,9 +249,9 @@ module Familia
             memberships
           end
 
-          # Check if this object is indexed in a specific target
+          # Check if this object is indexed in a specific scope
           # For class-level indexes, checks the hash key
-          # For target-scoped indexes, returns false (requires target instance)
+          # For instance-scoped indexes, returns false (requires scope instance)
           def indexed_in?(index_name)
             return false unless self.class.respond_to?(:indexing_relationships)
 
@@ -262,14 +262,12 @@ module Familia
             field_value = send(field)
             return false unless field_value
 
-            target_class = config.target_class
-
-            if target_class == self.class
+            if config.within.nil?
               # Class-level index (class_indexed_by) - check hash key using DataType
               index_hash = self.class.send(index_name)
               index_hash.key?(field_value.to_s)
             else
-              # Target-scoped index (indexed_by) - cannot verify without target instance
+              # Instance-scoped index (with within:) - cannot verify without scope instance
               false
             end
           end

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

@@ -1,3 +1,5 @@
+# lib/familia/features/relationships/indexing_relationship.rb
+#
 # frozen_string_literal: true
 
 module Familia
@@ -14,20 +16,30 @@ module Familia
       # Similar to ParticipationRelationship but for attribute-based lookups
       # rather than collection membership.
       #
+      # Terminology:
+      # - `scope_class`: The class that provides the uniqueness boundary for
+      #   instance-scoped indexes. For example, in `unique_index :badge_number,
+      #   :badge_index, within: Company`, the Company is the scope class.
+      # - `within`: Preserves the original DSL parameter to explicitly distinguish
+      #   class-level indexes (within: nil) from instance-scoped indexes (within:
+      #   SomeClass). This avoids brittle class comparisons and prevents issues
+      #   with inheritance scenarios.
+      #
       IndexingRelationship = Data.define(
         :field,              # Symbol - field being indexed (e.g., :email, :department)
         :index_name,         # Symbol - name of the index (e.g., :email_index, :dept_index)
-        :target_class,       # Class/Symbol - parent class for instance-scoped indexes (within:)
+        :scope_class,        # Class/Symbol - scope class for instance-scoped indexes (within:)
+        :within,             # Class/Symbol/nil - within: parameter (nil for class-level, Class for instance-scoped)
         :cardinality,        # Symbol - :unique (1:1) or :multi (1:many)
-        :query               # Boolean - whether to generate query  methods
+        :query,              # Boolean - whether to generate query  methods
       ) do
         #
-        # Get the normalized config name for the target class
+        # Get the normalized config name for the scope class
         #
         # @return [String] The config name (e.g., "user", "company", "test_company")
         #
-        def target_class_config_name
-          target_class.config_name
+        def scope_class_config_name
+          scope_class.config_name
         end
       end
     end