familia 2.0.0.pre19 → 2.0.0.pre22

data/lib/familia/horreum/persistence.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum/persistence.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # Familia::Horreum
@@ -35,164 +37,172 @@ module Familia
     # Handles conversion between Ruby objects and Valkey hash storage
     #
     module Persistence
-      # Persists the object to Valkey storage with automatic timestamping and validation.
+      # Persists object state to storage with timestamps, validation, and indexing.
       #
-      # Saves the current object state to Valkey storage, automatically setting
-      # created and updated timestamps if the object supports them. The method
-      # validates unique indexes before the transaction, commits all persistent
-      # fields, and optionally updates the key's expiration.
+      # Performs a complete save operation in an atomic transaction:
+      # - Sets created/updated timestamps
+      # - Validates unique index constraints
+      # - Persists all fields
+      # - Updates expiration (optional)
+      # - Updates class-level indexes
+      # - Adds to instances collection
       #
-      # @param update_expiration [Boolean] Whether to update the key's expiration
-      #   time after saving. Defaults to true.
+      # ## Transaction Safety
       #
-      # @return [Boolean] true if the save operation was successful, false otherwise.
+      # This method CANNOT be called within a transaction context. The save process
+      # requires reading current state to validate unique constraints, which would
+      # return uninspectable Redis::Future objects inside transactions.
       #
-      # @raise [Familia::OperationModeError] If called within an existing transaction.
-      #   Guards need to read current values, which is not possible inside MULTI/EXEC.
-      # @raise [Familia::RecordExistsError] If a unique index constraint is violated
-      #   for any class-level unique_index relationships.
+      # ### Correct Pattern:
+      #     customer = Customer.new(email: 'test@example.com')
+      #     customer.save  # Validates unique constraints here
       #
-      # @example Save an object to Valkey
-      #   user = User.new(name: "John", email: "john@example.com")
-      #   user.save
-      #   # => true
+      #     customer.transaction do
+      #       # Perform other atomic operations
+      #       customer.increment(:login_count)
+      #       customer.hset(:last_login, Time.now.to_i)
+      #     end
       #
-      # @example Save without updating expiration
-      #   user.save(update_expiration: false)
-      #   # => true
+      # ### Incorrect Pattern:
+      #     Customer.transaction do
+      #       customer = Customer.new(email: 'test@example.com')
+      #       customer.save  # Raises Familia::OperationModeError
+      #     end
       #
-      # @example Handle duplicate unique index
-      #   user2 = User.new(name: "Jane", email: "john@example.com")
-      #   user2.save
-      #   # => raises Familia::RecordExistsError
+      # @param update_expiration [Boolean] Whether to refresh key expiration (default: true)
+      # @return [Boolean] true on success
       #
-      # @note Cannot be called within a transaction. Call save first to start
-      #   the transaction, or use commit_fields/hmset for manual field updates
-      #   within transactions.
+      # @raise [Familia::OperationModeError] If called within a transaction
+      # @raise [Familia::RecordExistsError] If unique index constraint violated
       #
-      # @note When Familia.debug? is enabled, this method will trace the save
-      #   operation for debugging purposes.
+      # @example Basic usage
+      #   user = User.new(email: "john@example.com")
+      #   user.save  # => true
       #
-      # @see #commit_fields The underlying method that performs the field persistence
-      # @see #guard_unique_indexes! Automatic validation of class-level unique indexes
+      # @see #save_if_not_exists! For conditional saves
+      # @see #transaction For atomic operations after save
       #
       def save(update_expiration: true)
+        start_time = Familia.now_in_μs if Familia.debug?
+
         # Prevent save within transaction - unique index guards require read operations
         # which are not available in Redis MULTI/EXEC blocks
         if Fiber[:familia_transaction]
-          raise Familia::OperationModeError,
-            "Cannot call save within a transaction. Save operations must be called outside transactions to ensure unique constraints can be validated."
+          raise Familia::OperationModeError, <<~ERROR_MESSAGE
+            Cannot call save within a transaction. Save operations must be called outside transactions to ensure unique constraints can be validated.
+          ERROR_MESSAGE
         end
 
         Familia.trace :SAVE, nil, self.class.uri if Familia.debug?
 
-        # Update timestamp fields before saving
-        self.created ||= Familia.now if respond_to?(:created)
-        self.updated = Familia.now if respond_to?(:updated)
-
-        # Validate unique indexes BEFORE the transaction
-        guard_unique_indexes!
+        # Prepare object for persistence (timestamps, validation)
+        prepare_for_save
 
         # Everything in ONE transaction for complete atomicity
         result = transaction do |_conn|
-          # 1. Save all fields
-          prepared_h = to_h_for_storage
-          hmset_result = hmset(prepared_h)
-
-          # 2. Set expiration in same transaction
-          self.update_expiration if update_expiration
-
-          # 3. Update class-level indexes
-          auto_update_class_indexes
+          persist_to_storage(update_expiration)
+        end
 
-          # 4. Add to instances collection if available
-          self.class.instances.add(identifier, Familia.now) if self.class.respond_to?(:instances)
+        # Structured lifecycle logging and instrumentation
+        if Familia.debug? && start_time
+          duration = Familia.now_in_μs - start_time
+
+          begin
+            fields_count = to_h_for_storage.size
+          rescue => e
+            Familia.error "Failed to serialize fields for logging",
+              error: e.message,
+              class: self.class.name,
+              identifier: (identifier rescue nil)
+            fields_count = 0
+          end
 
-          hmset_result
+          Familia.debug "Horreum saved",
+            class: self.class.name,
+            identifier: identifier,
+            duration: duration,
+            fields_count: fields_count,
+            update_expiration: update_expiration
+
+          Familia::Instrumentation.notify_lifecycle(:save, self,
+            duration: duration,
+            update_expiration: update_expiration,
+            fields_count: fields_count
+          )
         end
 
-        Familia.ld "[save] #{self.class} #{dbkey} #{result} (update_expiration: #{update_expiration})"
-
         # Return boolean indicating success
         !result.nil?
       end
 
-      # Saves the object to Valkey storage only if it doesn't already exist.
-      #
-      # Conditionally persists the object to Valkey storage by first checking if the
-      # identifier field already exists. If the object already exists in storage,
-      # raises an error. Otherwise, proceeds with a normal save operation including
-      # automatic timestamping.
-      #
-      # This method provides atomic conditional creation to prevent duplicate objects
-      # from being saved when uniqueness is required based on the identifier field.
-      #
-      # @param update_expiration [Boolean] Whether to update the key's expiration
-      #   time after saving. Defaults to true.
-      #
-      # @return [Boolean] true if the save operation was successful
-      #
-      # @raise [Familia::RecordExistsError] If an object with the same identifier
-      #   already exists in Valkey storage
-      #
-      # @example Save a new user only if it doesn't exist
-      #   user = User.new(id: 123, name: "John")
-      #   user.save_if_not_exists
-      #   # => true (saved successfully)
+      # Conditionally persists object only if it doesn't already exist in storage.
       #
-      # @example Attempting to save an existing object
-      #   existing_user = User.new(id: 123, name: "Jane")
-      #   existing_user.save_if_not_exists
-      #   # => raises Familia::RecordExistsError
+      # Uses optimistic locking (WATCH) to atomically check existence and save.
+      # If the object doesn't exist, performs identical operations as save.
+      # If it exists, raises an error with retry logic for optimistic lock failures.
       #
-      # @example Save without updating expiration
-      #   user.save_if_not_exists(update_expiration: false)
-      #   # => true
-      #
-      # @note This method uses HSETNX to atomically check and set the identifier
-      #   field, ensuring race-condition-free conditional creation.
+      # `save_if_not_exists` doesn't call save because of the gap between checking
+      # existence and persisting the data. We can't check for existence inside the
+      # transaction because commands are queued and not executed until EXEC
+      # is called (if you try you get a Redis::Future object). So here we use a
+      # WATCH + MULTI/EXEC pattern to fail the transaction if the key is created
+      # (or modified in any way) to avoid silent data corruption♀︎.
+
+      # ♀︎ Additional note about WATCH + MULTI/EXEC in Valkey/Redis or any two
+      # step existence check in any database: although it is more cautious,
+      # it is not atomic. The only way to do that is if the database process
+      # can determine itself whether the record already exists or not. For
+      # Valkey/Redis, that means writing the lua to do that.
       #
-      # @see #save The underlying save method called when the object doesn't exist
+      # @param update_expiration [Boolean] Whether to refresh key expiration (default: true)
+      # @return [Boolean] true on successful save
       #
-      # Check if save_if_not_exists is implemented correctly. It should:
+      # @raise [Familia::RecordExistsError] If object already exists
+      # @raise [Familia::OptimisticLockError] If retries exhausted (max 3 attempts)
+      # @raise [Familia::OperationModeError] If called within a transaction
       #
-      # Check if record exists
-      # If exists, raise Familia::RecordExistsError
-      # If not exists, save
+      # @example
+      #   user = User.new(id: 123)
+      #   user.save_if_not_exists!  # => true or raises
       def save_if_not_exists!(update_expiration: true)
         # Prevent save_if_not_exists! within transaction - needs to read existence state
         if Fiber[:familia_transaction]
-          raise Familia::OperationModeError,
-            "Cannot call save_if_not_exists! within a transaction. This method must be called outside transactions to properly check existence."
+          raise Familia::OperationModeError, <<~ERROR_MESSAGE
+            Cannot call save_if_not_exists! within a transaction. This method
+            must be called outside transactions to properly check existence.
+          ERROR_MESSAGE
         end
 
         identifier_field = self.class.identifier_field
 
-        Familia.ld "[save_if_not_exists]: #{self.class} #{identifier_field}=#{identifier}"
+        Familia.debug "[save_if_not_exists]: #{self.class} #{identifier_field}=#{identifier}"
         Familia.trace :SAVE_IF_NOT_EXISTS, nil, self.class.uri if Familia.debug?
 
+        # Prepare object for persistence (timestamps, validation)
+        prepare_for_save
+
         attempts = 0
         begin
           attempts += 1
 
-          watch do
+          result = watch do
             raise Familia::RecordExistsError, dbkey if exists?
 
             txn_result = transaction do |_multi|
-              hmset(to_h_for_storage)
-
-              self.update_expiration if update_expiration
-
-              # Auto-index for class-level indexes after successful save
-              auto_update_class_indexes
+              persist_to_storage(update_expiration)
             end
 
-            Familia.ld "[save_if_not_exists]: txn_result=#{txn_result.inspect}"
+            Familia.debug "[save_if_not_exists]: txn_result=#{txn_result.inspect}"
 
-            txn_result.successful?
+            txn_result
           end
+
+          Familia.debug "[save_if_not_exists]: result=#{result.inspect}"
+
+          # Return boolean indicating success (consistent with save method)
+          !result.nil?
         rescue OptimisticLockError => e
-          Familia.ld "[save_if_not_exists]: OptimisticLockError (#{attempts}): #{e.message}"
+          Familia.debug "[save_if_not_exists]: OptimisticLockError (#{attempts}): #{e.message}"
           raise if attempts >= 3
 
           sleep(0.001 * (2**attempts))
@@ -200,9 +210,13 @@ module Familia
         end
       end
 
+      # Non-raising variant of save_if_not_exists!
+      #
+      # @return [Boolean] true on success, false if object exists
+      # @raise [Familia::OptimisticLockError] If concurrency conflict persists after retries
       def save_if_not_exists(...)
         save_if_not_exists!(...)
-      rescue RecordExistsError, OptimisticLockError
+      rescue RecordExistsError
         false
       end
 
@@ -233,7 +247,7 @@ module Familia
       #
       def commit_fields(update_expiration: true)
         prepared_value = to_h_for_storage
-        Familia.ld "[commit_fields] Begin #{self.class} #{dbkey} #{prepared_value} (exp: #{update_expiration})"
+        Familia.debug "[commit_fields] Begin #{self.class} #{dbkey} #{prepared_value} (exp: #{update_expiration})"
 
         transaction do |_conn|
           # Set all fields atomically
@@ -367,7 +381,7 @@ module Familia
         Familia.trace :DESTROY!, dbkey, self.class.uri
 
         # Execute all deletion operations within a transaction
-        transaction do |_conn|
+        result = transaction do |_conn|
           # Delete the main object key
           delete!
 
@@ -382,7 +396,20 @@ module Familia
               obj.delete!
             end
           end
+
+          # Remove from instances collection if available
+          self.class.instances.remove(identifier) if self.class.respond_to?(:instances)
         end
+
+        # Structured lifecycle logging and instrumentation
+        Familia.debug "Horreum destroyed",
+          class: self.class.name,
+          identifier: identifier,
+          key: dbkey
+
+        Familia::Instrumentation.notify_lifecycle(:destroy, self, key: dbkey)
+
+        result
       end
 
       # Clears all fields by setting them to nil.
@@ -433,7 +460,7 @@ module Familia
         raise Familia::KeyNotFoundError, dbkey unless dbclient.exists(dbkey)
 
         fields = hgetall
-        Familia.ld "[refresh!] #{self.class} #{dbkey} fields:#{fields.keys}"
+        Familia.debug "[refresh!] #{self.class} #{dbkey} fields:#{fields.keys}"
 
         # Reset transient fields to nil for semantic clarity and ORM consistency
         # Transient fields have no authoritative source, so they should return to
@@ -489,7 +516,7 @@ module Familia
 
           # UnsortedSet the transient field back to nil
           send("#{field_type.method_name}=", nil)
-          Familia.ld "[reset_transient_fields!] Reset #{field_name} to nil"
+          Familia.debug "[reset_transient_fields!] Reset #{field_name} to nil"
         end
       end
 
@@ -563,7 +590,7 @@ module Familia
           # Instance-scoped indexes must be manually populated because they need
           # the scope instance reference (e.g., employee.add_to_company_badge_index(company))
           if rel.within
-            Familia.ld <<~LOG_MESSAGE
+            Familia.debug <<~LOG_MESSAGE
               [auto_update_class_indexes] Skipping #{rel.index_name} (requires scope context)
             LOG_MESSAGE
             next
@@ -574,6 +601,50 @@ module Familia
           send(add_method) if respond_to?(add_method)
         end
       end
+
+      # Prepares the object for persistence by setting timestamps and validating constraints
+      #
+      # This method is called by both save and save_if_not_exists to ensure consistent
+      # preparation logic. It updates created/updated timestamps and validates unique
+      # indexes before the transaction begins.
+      #
+      # @return [void]
+      #
+      def prepare_for_save
+        # Update timestamp fields before saving
+        self.created ||= Familia.now if respond_to?(:created)
+        self.updated = Familia.now if respond_to?(:updated)
+
+        # Validate unique indexes BEFORE the transaction
+        guard_unique_indexes!
+      end
+      private :prepare_for_save
+
+      # Persists the object's data to storage within a transaction
+      #
+      # This method contains the core persistence logic shared by both save and
+      # save_if_not_exists. It must be called within a transaction block.
+      #
+      # @param update_expiration [Boolean] Whether to update the key's expiration
+      # @return [Object] The result of the hmset operation
+      #
+      def persist_to_storage(update_expiration)
+        # 1. Save all fields to hashkey at once
+        prepared_h = to_h_for_storage
+        hmset_result = hmset(prepared_h)
+
+        # 2. Set expiration in same transaction
+        self.update_expiration if update_expiration
+
+        # 3. Update class-level indexes
+        auto_update_class_indexes
+
+        # 4. Add to instances collection if available
+        self.class.instances.add(identifier, Familia.now) if self.class.respond_to?(:instances)
+
+        hmset_result
+      end
+      private :persist_to_storage
     end
   end
 end

data/lib/familia/horreum/related_fields.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum/related_fields.rb
+#
+# frozen_string_literal: true
 
 module Familia
 

data/lib/familia/horreum/serialization.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum/serialization.rb
+#
+# frozen_string_literal: true
 
 module Familia
   class Horreum
@@ -30,7 +32,7 @@ module Familia
           next unless field_type.loggable
 
           val = send(field_type.method_name)
-          Familia.ld " [to_h] field: #{field} val: #{val.class}"
+          Familia.debug " [to_h] field: #{field} val: #{val.class}"
 
           # Use string key for external API compatibility
           # Return Ruby values, not JSON-encoded strings
@@ -63,7 +65,7 @@ module Familia
           prepared = serialize_value(val)
 
           if Familia.debug?
-            Familia.ld " [to_h_for_storage] field: #{field} val: #{val.class} prepared: #{prepared&.class || '[nil]'}"
+            Familia.debug " [to_h_for_storage] field: #{field} val: #{val.class} prepared: #{prepared&.class || '[nil]'}"
           end
 
           # Use string key for database compatibility
@@ -96,7 +98,7 @@ module Familia
 
           method_name = field_type.method_name
           val = send(method_name)
-          Familia.ld " [to_a] field: #{field} method: #{method_name} val: #{val.class}"
+          Familia.debug " [to_a] field: #{field} method: #{method_name} val: #{val.class}"
 
           # Return actual Ruby values, including nil to maintain array positions
           val
@@ -182,7 +184,24 @@ module Familia
           "Legacy plain string in #{context}: #{val.inspect} (#{dbkey_info})"
         end
 
-        Familia.le(msg)
+        # Structured error logging with instrumentation
+        error_type = looks_like_json?(val) ? :corrupted_json : :legacy_string
+        Familia.error msg,
+          error_type: error_type,
+          field: field_name,
+          value_preview: val.to_s[0...50],
+          object_class: self.class.name,
+          identifier: (identifier rescue nil),
+          key: dbkey_info
+
+        # Notify instrumentation hooks
+        Familia::Instrumentation.notify_error(
+          StandardError.new(msg),
+          operation: :deserialization,
+          error_type: error_type,
+          field: field_name,
+          object_class: self.class.name
+        )
       end
 
       def looks_like_json?(val)

data/lib/familia/horreum/settings.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum/settings.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # InstanceMethods - Module containing instance-level methods for Familia

data/lib/familia/horreum/utils.rb

@@ -1,5 +1,7 @@
 # lib/familia/horreum/utils.rb
 #
+# frozen_string_literal: true
+
 module Familia
   # InstanceMethods - Module containing instance-level methods for Familia
   #

data/lib/familia/horreum.rb

@@ -1,4 +1,6 @@
 # lib/familia/horreum.rb
+#
+# frozen_string_literal: true
 
 require_relative 'horreum/settings'
 require_relative 'horreum/connection'
@@ -186,6 +188,7 @@ module Familia
     #   `Session.new({sessid: "abc123", custid: "user456"})` # legacy hash (robust)
     #
     def initialize(*args, **kwargs)
+      start_time = Familia.now_in_μs if Familia.debug?
       Familia.trace :INITIALIZE, nil, "Initializing #{self.class}" if Familia.debug?
       initialize_relatives
 
@@ -236,6 +239,17 @@ module Familia
       #   end
       #
       init
+
+      # Structured lifecycle logging and instrumentation
+      if Familia.debug? && start_time
+        duration = Familia.now_in_μs - start_time
+        Familia.debug "Horreum initialized",
+          class: self.class.name,
+          duration: duration,
+          identifier: (identifier rescue nil)
+
+        Familia::Instrumentation.notify_lifecycle(:initialize, self, duration: duration)
+      end
     end
 
     # Initialization method called at the end of initialize
@@ -338,7 +352,7 @@ module Familia
     #   the object with.
     # @return [Array] The list of field names that were updated.
     def naive_refresh(**fields)
-      Familia.ld "[naive_refresh] #{self.class} #{dbkey} #{fields.keys}"
+      Familia.debug "[naive_refresh] #{self.class} #{dbkey} #{fields.keys}"
       initialize_with_keyword_args_deserialize_value(**fields)
     end
 

data/lib/familia/identifier_extractor.rb

@@ -1,4 +1,6 @@
 # lib/familia/identifier_extractor.rb
+#
+# frozen_string_literal: true
 
 module Familia
   # IdentifierExtractor - Extracts identifiers from Familia objects for storage
@@ -27,7 +29,7 @@ module Familia
     # @return [String] The extracted identifier or class name
     # @raise [Familia::NotDistinguishableError] If value is not a Class or Familia::Base
     #
-    def identifier_extractor(value, strict_values: true)
+    def identifier_extractor(value)
       case value
       when ::Symbol, ::String, ::Integer, ::Float
         Familia.trace :IDENTIFIER_EXTRACTOR, nil, 'simple_value' if Familia.debug?