familia 2.0.0.pre17 → 2.0.0.pre19

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

@@ -49,11 +49,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 +63,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 +74,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 +86,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,47 +95,57 @@ 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)
 
             # Generate instance query method (e.g., company.find_by_badge_number)
-            actual_target_class.class_eval do
-              define_method("find_by_#{field}") do |field_value|
+            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)
 
-                # Get the identifier from the hash
-                object_id = index_hash[field_value.to_s]
-                return nil unless object_id
+                # Get the identifier from the hash 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
+                # with the broader DataType API patterns used throughout Familia.
+                record_id = index_hash.get(provided_value)
+                return nil unless record_id
 
-                indexed_class.new(object_id)
+                indexed_class.find_by_identifier(record_id)
               end
 
               # Generate bulk query method (e.g., company.find_all_by_badge_number)
-              define_method("find_all_by_#{field}") do |field_values|
-                field_values = Array(field_values)
-                return [] if field_values.empty?
+              define_method(:"find_all_by_#{field}") do |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
                 index_hash = send(index_name)
 
                 # Get all identifiers from the hash
-                object_ids = index_hash.values_at(*field_values.map(&:to_s))
-                # Filter out nil values and instantiate objects
-                object_ids.compact.map { |object_id| indexed_class.new(object_id) }
+                record_ids = index_hash.values_at(*provided_ids.map(&:to_s))
+
+                # Filter out nil values (non-existent records) and instantiate objects
+                record_ids.compact.map { |record_id|
+                  indexed_class.find_by_identifier(record_id)
+                }
               end
 
               # Accessor method already created by ensure_index_field above
               # No need to manually define it here
 
               # Generate method to rebuild the unique index for this parent instance
-              define_method("rebuild_#{index_name}") do
+              define_method(:"rebuild_#{index_name}") do
                 # Use declared field accessor instead of manual instantiation
                 index_hash = send(index_name)
 
@@ -147,63 +159,102 @@ module Familia
             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}"
+              method_name = :"add_to_#{scope_class_config}_#{index_name}"
               Familia.ld("[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}"
+              # 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.ld("[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)
+                # 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.ld("[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 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}"
+              method_name = :"update_in_#{scope_class_config}_#{index_name}"
               Familia.ld("[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
@@ -222,31 +273,47 @@ module Familia
           # - Employee.email_index
           # - Employee.rebuild_email_index
           def generate_query_methods_class(field, index_name, indexed_class)
-            indexed_class.define_singleton_method("find_by_#{field}") do |field_value|
-              index_hash = send(index_name) # Access the class-level hashkey DataType
-              object_id = index_hash[field_value.to_s]
+            # 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
+
+              # 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
+              # with the broader DataType API patterns used throughout Familia.
+              record_id = index_hash.get(provided_id)
 
-              return nil unless object_id
+              return nil unless record_id
 
-              new(object_id)
+              indexed_class.find_by_identifier(record_id)
             end
 
             # Generate class-level bulk query method
-            indexed_class.define_singleton_method("find_all_by_#{field}") do |field_values|
-              field_values = Array(field_values)
-              return [] if field_values.empty?
-
-              index_hash = send(index_name) # Access the class-level hashkey DataType
-              object_ids = index_hash.values_at(*field_values.map(&:to_s))
-              # Filter out nil values and instantiate objects
-              object_ids.compact.map { |object_id| new(object_id) }
+            indexed_class.define_singleton_method(:"find_all_by_#{field}") do |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
+
+              # 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 (non-existent records) and instantiate objects
+              record_ids.compact.map { |record_id|
+                indexed_class.find_by_identifier(record_id)
+              }
             end
 
             # The index accessor method is already created by the class_hashkey declaration
             # 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
+            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
@@ -265,16 +332,35 @@ module Familia
           # - employee.update_in_class_email_index(old_email)
           def generate_mutation_methods_class(field, index_name, indexed_class)
             indexed_class.class_eval do
-              define_method("add_to_class_#{index_name}") do
+              define_method(:"add_to_class_#{index_name}") do
                 index_hash = self.class.send(index_name)  # Access the class-level hashkey DataType
                 field_value = send(field)
 
                 return unless field_value
 
+                # Just set the value - uniqueness should be validated before save
                 index_hash[field_value.to_s] = identifier
               end
 
-              define_method("remove_from_class_#{index_name}") do
+              # 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)
 
@@ -283,7 +369,7 @@ module Familia
                 index_hash.remove(field_value.to_s)
               end
 
-              define_method("update_in_class_#{index_name}") do |old_field_value = nil|
+              define_method(:"update_in_class_#{index_name}") do |old_field_value = nil|
                 new_field_value = send(field)
 
                 # Use class-level transaction for atomicity with DataType abstraction

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

@@ -50,7 +50,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 +89,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 +109,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 +136,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 +208,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 +228,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 +246,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 +259,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

@@ -14,20 +14,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
       ) 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

data/lib/familia/features/safe_dump.rb

@@ -1,9 +1,8 @@
 # lib/familia/features/safe_dump.rb
 
 #
-#   Class instance variables are used here for feature configuration
-#   (e.g., @dump_method, @load_method). These are set once and not mutated
-#   at runtime, so thread safety is not a concern for this feature.
+# Class instance variables are used here for configuration. These are set
+# once at loadtime and not mutated, so thread safety is not an issue here.
 #
 module Familia
   module Features

data/lib/familia/field_type.rb

@@ -143,7 +143,8 @@ module Familia
           val = args.first
 
           # If no value provided, return current stored value
-          return hget(field_name) if val.nil?
+          # Handle Redis::Future objects during transactions
+          return hget(field_name) if val.nil? || val.is_a?(Redis::Future)
 
           begin
             # Trace the operation if debugging is enabled