familia 2.0.0.pre15 → 2.0.0.pre17

data/lib/familia/horreum/serialization.rb

@@ -0,0 +1,172 @@
+# lib/familia/horreum/serialization.rb
+
+module Familia
+  class Horreum
+    # Serialization - Instance-level methods for object serialization
+    # Handles conversion between Ruby objects and Valkey hash storage
+    module Serialization
+      # Converts the object's persistent fields to a hash for external use.
+      #
+      # Serializes persistent field values for external consumption (APIs, logs),
+      # excluding non-loggable fields like encrypted fields for security.
+      # Only non-nil values are included in the resulting hash.
+      #
+      # @return [Hash] Hash with field names as keys and serialized values
+      #   safe for external exposure
+      #
+      # @example Converting an object to hash format for API response
+      #   user = User.new(name: "John", email: "john@example.com", age: 30)
+      #   user.to_h
+      #   # => {"name"=>"John", "email"=>"john@example.com", "age"=>"30"}
+      #   # encrypted fields are excluded for security
+      #
+      # @note Only loggable fields are included for security
+      # @note Only fields with non-nil values are included
+      #
+      def to_h
+        self.class.persistent_fields.each_with_object({}) do |field, hsh|
+          field_type = self.class.field_types[field]
+
+          # Security: Skip non-loggable fields (e.g., encrypted fields)
+          next unless field_type.loggable
+
+          method_name = field_type.method_name
+          val = send(method_name)
+          prepared = serialize_value(val)
+          Familia.ld " [to_h] field: #{field} val: #{val.class} prepared: #{prepared&.class || '[nil]'}"
+
+          # Only include non-nil values in the hash for Valkey
+          # Use string key for database compatibility
+          hsh[field.to_s] = prepared unless prepared.nil?
+        end
+      end
+
+      # Converts the object's persistent fields to a hash for database storage.
+      #
+      # Serializes ALL persistent field values for database storage, including
+      # encrypted fields. This is used internally by commit_fields and other
+      # persistence operations.
+      #
+      # @return [Hash] Hash with field names as keys and serialized values
+      #   ready for database storage
+      #
+      # @note Includes ALL persistent fields, including encrypted fields
+      # @note Only fields with non-nil values are included for storage efficiency
+      #
+      def to_h_for_storage
+        self.class.persistent_fields.each_with_object({}) do |field, hsh|
+          field_type = self.class.field_types[field]
+          method_name = field_type.method_name
+          val = send(method_name)
+          prepared = serialize_value(val)
+          Familia.ld " [to_h_for_storage] field: #{field} val: #{val.class} prepared: #{prepared&.class || '[nil]'}"
+
+          # Only include non-nil values in the hash for Valkey
+          # Use string key for database compatibility
+          hsh[field.to_s] = prepared unless prepared.nil?
+        end
+      end
+
+      # Converts the object's persistent fields to an array.
+      #
+      # Serializes all persistent field values in field definition order,
+      # preparing them for Valkey storage. Each value is processed through
+      # the serialization pipeline to ensure Valkey compatibility.
+      #
+      # @return [Array] Array of serialized field values in field order
+      #
+      # @example Converting an object to array format
+      #   user = User.new(name: "John", email: "john@example.com", age: 30)
+      #   user.to_a
+      #   # => ["John", "john@example.com", "30"]
+      #
+      # @note Values are serialized using the same process as other persistence
+      #   methods to maintain data consistency across operations.
+      #
+      def to_a
+        self.class.persistent_fields.filter_map do |field|
+          field_type = self.class.field_types[field]
+
+          # Security: Skip non-loggable fields (e.g., encrypted fields)
+          next unless field_type.loggable
+
+          method_name = field_type.method_name
+          val = send(method_name)
+          prepared = serialize_value(val)
+          Familia.ld " [to_a] field: #{field} method: #{method_name} val: #{val.class} prepared: #{prepared.class}"
+          prepared
+        end
+      end
+
+      # Serializes a Ruby object for Valkey storage.
+      #
+      # Converts Ruby objects into the DB-compatible string representations using
+      # the Familia distinguisher for type coercion. Falls back to JSON serialization
+      # for complex types (Hash, Array) when the primary distinguisher returns nil.
+      #
+      # The serialization process:
+      # 1. Attempts conversion using Familia.distinguisher with relaxed type checking
+      # 2. For Hash/Array types that return nil, tries custom dump_method or Familia::JsonSerializer.dump
+      # 3. Logs warnings when serialization fails completely
+      #
+      # @param val [Object] The Ruby object to serialize for Valkey storage
+      #
+      # @return [String, nil] The serialized value ready for Valkey storage, or nil
+      #   if serialization failed
+      #
+      # @example Serializing different data types
+      #   serialize_value("hello")        # => "hello"
+      #   serialize_value(42)             # => "42"
+      #   serialize_value({name: "John"}) # => '{"name":"John"}'
+      #   serialize_value([1, 2, 3])      # => "[1,2,3]"
+      #
+      # @note This method integrates with Familia's type system and supports
+      #   custom serialization methods when available on the object
+      #
+      # @see Familia.distinguisher The primary serialization mechanism
+      #
+      def serialize_value(val)
+        # Security: Handle ConcealedString safely - extract encrypted data for storage
+        return val.encrypted_value if val.respond_to?(:encrypted_value)
+
+        prepared = Familia.distinguisher(val, strict_values: false)
+
+        # If the distinguisher returns nil, try using the dump_method but only
+        # use JSON serialization for complex types that need it.
+        if prepared.nil? && (val.is_a?(Hash) || val.is_a?(Array))
+          prepared = val.respond_to?(dump_method) ? val.send(dump_method) : Familia::JsonSerializer.dump(val)
+        end
+
+        # If both the distinguisher and dump_method return nil, log an error
+        Familia.ld "[#{self.class}#serialize_value] nil returned for #{self.class}" if prepared.nil?
+
+        prepared
+      end
+
+      # Converts a Database string value back to its original Ruby type
+      #
+      # This method attempts to deserialize JSON strings back to their original
+      # Hash or Array types. Simple string values are returned as-is.
+      #
+      # @param val [String] The string value from Database to deserialize
+      # @param symbolize [Boolean] Whether to symbolize hash keys (default: true for compatibility)
+      # @return [Object] The deserialized value (Hash, Array, or original string)
+      #
+      def deserialize_value(val, symbolize: true)
+        return val if val.nil? || val == ''
+
+        # Try to parse as JSON first for complex types
+        begin
+          parsed = Familia::JsonSerializer.parse(val, symbolize_names: symbolize)
+          # Only return parsed value if it's a complex type (Hash/Array)
+          # Simple values should remain as strings
+          return parsed if parsed.is_a?(Hash) || parsed.is_a?(Array)
+        rescue Familia::SerializerError
+          # Not valid JSON, return as-is
+        end
+
+        val
+      end
+    end
+  end
+end

data/lib/familia/horreum/{shared/settings.rb → settings.rb}

@@ -7,7 +7,8 @@ module Familia
   # instance-level functionality for Database operations and object management.
   #
   class Horreum
-    # Settings - Module containing settings for Familia::Horreum (InstanceMethods)
+    # Settings - Instance-level configuration methods for Horreum models
+    # Provides per-instance settings like logical_database, dump_method, load_method, suffix
     #
     module Settings
       attr_writer :dump_method, :load_method, :suffix

data/lib/familia/horreum/{core/utils.rb → utils.rb}

@@ -7,7 +7,8 @@ module Familia
   # instance-level functionality for Database operations and object management.
   #
   class Horreum
-    # Utils - Module containing utility methods for Familia::Horreum (InstanceMethods)
+    # Utils - Instance-level utility methods for Familia::Horreum
+    # Provides identifier handling, dbkey generation, and object inspection
     #
     module Utils
       # def uri

data/lib/familia/horreum.rb

@@ -1,100 +1,193 @@
 # lib/familia/horreum.rb
 
-require_relative 'horreum/subclass/definition'
-require_relative 'horreum/subclass/management'
-require_relative 'horreum/shared/settings'
-require_relative 'horreum/core'
+require_relative 'horreum/settings'
+require_relative 'horreum/connection'
+require_relative 'horreum/database_commands'
+require_relative 'horreum/related_fields'
+require_relative 'horreum/definition'
+require_relative 'horreum/management'
+require_relative 'horreum/persistence'
+require_relative 'horreum/serialization'
+require_relative 'horreum/utils'
 
 module Familia
   #
-  # Horreum: A module for managing Redis-based object storage and relationships
+  # Horreum: A Valkey/Redis-backed ORM base class providing field definitions and DataType relationships
   #
-  # Key features:
-  # * Provides instance-level access to a single hash in Redis
-  # * Includes Familia for class/module level access to Database types and operations
-  # * Uses 'hashkey' to define a Database hash referred to as "object"
-  # * Applies a default expiry (5 years) to all keys
+  # Familia::Horreum serves as the foundation for creating Ruby objects that are persisted
+  # to and retrieved from Valkey/Redis. It provides a comprehensive field system, DataType
+  # relationships, and automated key generation for seamless object-relational mapping.
   #
-  # Metaprogramming:
-  # * The class << self block defines class-level behavior
-  # * The `inherited` method extends ClassMethods to subclasses like
-  #  `MyModel` in the example below
+  # Core Features:
+  # * Field definition system with automatic getter/setter/fast writer generation
+  # * DataType relationships (sets, lists, hashes, sorted sets, counters, locks)
+  # * Flexible identifier strategies (symbols, procs, arrays)
+  # * Automatic Redis key generation and management
+  # * Feature system for modular functionality (expiration, safe_dump, relationships)
+  # * Thread-safe DataType instances with automatic freezing
+  # * Multiple initialization patterns for different use cases
+  #
+  # Architecture:
+  # * Inheriting classes automatically extend definition and management methods
+  # * Instance-level DataTypes are created per object with unique Redis keys
+  # * Class-level DataTypes are shared across all instances
+  # * All objects tracked in Familia.members for reloading and introspection
   #
   # Usage:
-  #   class MyModel < Familia::Horreum
+  #   class User < Familia::Horreum
+  #     identifier_field :email
   #     field :name
-  #     field :email
+  #     field :created_at
+  #     set :tags
+  #     list :activity_log
+  #     feature :expiration
   #   end
   #
+  #   user = User.new(email: "john@example.com", name: "John")
+  #   user.tags << "premium"
+  #   user.save
+  #
   class Horreum
     include Familia::Base
-    include Familia::Horreum::Core
+    include Familia::Horreum::Persistence
+    include Familia::Horreum::Serialization
+    include Familia::Horreum::Connection
+    include Familia::Horreum::DatabaseCommands
     include Familia::Horreum::Settings
+    include Familia::Horreum::Utils
 
     using Familia::Refinements::TimeLiterals
 
-    # Singleton Class Context
+    # Class-Level Inheritance and Extension Management
     #
-    # The code within this block operates on the singleton class (also known as
-    # eigenclass or metaclass) of the current class. This means:
+    # This singleton class block defines the metaclass behavior that governs how
+    # Familia::Horreum subclasses are configured and extended when they inherit.
     #
-    # 1. Methods defined here become class methods, not instance methods.
-    # 2. Constants and variables set here belong to the class, not instances.
-    # 3. This is the place to define class-level behavior and properties.
+    # Key Responsibilities:
+    # * Automatically extend subclasses with essential functionality modules
+    # * Register new classes in Familia.members for tracking and reloading
+    # * Provide class-level attribute accessors for configuration
+    # * Establish the inheritance chain that enables the Horreum ORM pattern
     #
-    # Use this context for:
-    # * Defining class methods
-    # * Setting class-level configurations
-    # * Creating factory methods
-    # * Establishing relationships with other classes
+    # When a class inherits from Horreum, the inherited() hook automatically:
+    # * Extends DefinitionMethods (field, identifier_field, dbkey definitions)
+    # * Extends ManagementMethods (create, find, destroy operations)
+    # * Extends Connection (database client and connection management)
+    # * Extends Features (feature loading and configuration)
+    # * Registers the class in Familia.members for introspection
     #
-    # Example:
-    #   class MyClass
-    #     class << self
-    #       def class_method
-    #         puts "This is a class method"
-    #       end
-    #     end
-    #   end
-    #
-    #   MyClass.class_method  # => "This is a class method"
-    #
-    # Note: Changes made here affect the class itself and all future instances,
-    # but not existing instances of the class.
+    # Class-Level Attributes:
+    # * @parent - Parent object reference for nested relationships
+    # * @dbclient - Database connection override for this class
+    # * @dump_method/@load_method - Serialization method configuration
+    # * @has_related_fields - Flag indicating if DataType relationships are defined
     #
     class << self
       attr_accessor :parent
       # TODO: Where are we calling dbclient= from now with connection pool?
       attr_writer :dbclient, :dump_method, :load_method
-      attr_reader :has_relations
+      attr_reader :has_related_fields
 
       # Extends ClassMethods to subclasses and tracks Familia members
       def inherited(member)
-        Familia.trace :HORREUM, nil, "Welcome #{member} to the family", caller(1..1) if Familia.debug?
+        Familia.trace :HORREUM, nil, "Welcome #{member} to the family" if Familia.debug?
 
         # Class-level functionality extensions:
         member.extend(Familia::Horreum::DefinitionMethods)    # field(), identifier_field(), dbkey()
         member.extend(Familia::Horreum::ManagementMethods)    # create(), find(), destroy!()
         member.extend(Familia::Horreum::Connection)           # dbclient, connection management
-        member.extend(Familia::Features)             # feature() method for optional modules
+        member.extend(Familia::Features) # feature() method for optional modules
+
+        # Copy parent class configuration to child class
+        # This implements conventional ORM inheritance behavior where child classes
+        # automatically inherit all parent configuration without manual copying
+        parent_class = member.superclass
+        if parent_class.respond_to?(:identifier_field) && parent_class != Familia::Horreum
+          # Copy essential configuration instance variables from parent
+          if parent_class.identifier_field
+            member.instance_variable_set(:@identifier_field, parent_class.identifier_field)
+          end
+
+          # Copy field system configuration
+          member.instance_variable_set(:@fields, parent_class.fields.dup) if parent_class.fields&.any?
+
+          if parent_class.respond_to?(:field_types) && parent_class.field_types&.any?
+            # Copy field_types hash (FieldType instances are frozen/immutable and can be safely shared)
+            copied_field_types = parent_class.field_types.dup
+            member.instance_variable_set(:@field_types, copied_field_types)
+            # Re-install field methods on the child class using proper method name detection
+            parent_class.field_types.each_value do |field_type|
+              # Collect all method names that field_type.install will create
+              methods_to_check = [
+                field_type.method_name,
+                (field_type.method_name ? :"#{field_type.method_name}=" : nil),
+                field_type.fast_method_name,
+              ].compact
+
+              # Only install if none of the methods already exist
+              methods_exist = methods_to_check.any? do |method_name|
+                member.method_defined?(method_name) || member.private_method_defined?(method_name)
+              end
+
+              field_type.install(member) unless methods_exist
+            end
+          end
+
+          # Copy features configuration
+          if parent_class.respond_to?(:features_enabled) && parent_class.features_enabled&.any?
+            member.instance_variable_set(:@features_enabled, parent_class.features_enabled.dup)
+          end
+
+          # Copy other configuration using consistent instance variable access
+          if (prefix = parent_class.instance_variable_get(:@prefix))
+            member.instance_variable_set(:@prefix, prefix)
+          end
+          if (suffix = parent_class.instance_variable_get(:@suffix))
+            member.instance_variable_set(:@suffix, suffix)
+          end
+          if (logical_db = parent_class.instance_variable_get(:@logical_database))
+            member.instance_variable_set(:@logical_database, logical_db)
+          end
+          if (default_exp = parent_class.instance_variable_get(:@default_expiration))
+            member.instance_variable_set(:@default_expiration, default_exp)
+          end
+
+          # Copy DataType relationships
+          if parent_class.class_related_fields&.any?
+            member.instance_variable_set(:@class_related_fields, parent_class.class_related_fields.dup)
+          end
+          if parent_class.related_fields&.any?
+            member.instance_variable_set(:@related_fields, parent_class.related_fields.dup)
+          end
+          if parent_class.instance_variable_get(:@has_related_fields)
+            member.instance_variable_set(:@has_related_fields,
+                                         parent_class.instance_variable_get(:@has_related_fields))
+          end
+        end
 
         # Track all classes that inherit from Horreum
         Familia.members << member
+
+        # Set up automatic instance tracking using built-in class_sorted_set
+        member.class_sorted_set :instances
+
         super
       end
     end
 
+    attr_writer :dbclient
+
     # Instance initialization
-    # This method sets up the object's state, including Redis-related data.
+    # This method sets up the object's state, including Valkey/Redis-related data.
     #
     # Usage:
     #
-    #   Session.new("abc123", "user456")                   # positional (brittle)
-    #   Session.new(sessid: "abc123", custid: "user456")   # hash (robust)
-    #   Session.new({sessid: "abc123", custid: "user456"}) # legacy hash (robust)
+    #   `Session.new("abc123", "user456")`                   # positional (brittle)
+    #   `Session.new(sessid: "abc123", custid: "user456")`   # hash (robust)
+    #   `Session.new({sessid: "abc123", custid: "user456"})` # legacy hash (robust)
     #
     def initialize(*args, **kwargs)
-      Familia.trace :INITIALIZE, dbclient, "Initializing #{self.class}", caller(1..1) if Familia.debug?
+      Familia.trace :INITIALIZE, nil, "Initializing #{self.class}" if Familia.debug?
       initialize_relatives
 
       # No longer auto-create a key field - the identifier method will
@@ -108,15 +201,16 @@ module Familia
 
       # Initialize object with arguments using one of four strategies:
       #
-      # 1. **Identifier** (Recommended for lookups): A single argument is treated as the identifier.
-      #    Example: Customer.new("cust_123")
-      #    - Robust and convenient for creating objects from an ID.
+      # 1. **Identifier** (Recommended for lookups): A single argument is
+      #     treated as the identifier. Robust and convenient for creating
+      #     objects from an ID. e.g. `Customer.new("cust_123")`
       #
-      # 2. **Keyword Arguments** (Recommended for creation): Order-independent field assignment
-      #    Example: Customer.new(name: "John", email: "john@example.com")
+      # 2. **Keyword Arguments** (Recommended for creation): Order-independent
+      #     field assignment
+      #    e.g. Customer.new(name: "John", email: "john@example.com")
       #
       # 3. **Positional Arguments** (Legacy): Field assignment by definition order
-      #    Example: Customer.new("cust_123", "John", "john@example.com")
+      #    e.g. Customer.new("cust_123", "John", "john@example.com")
       #
       # 4. **No Arguments**: Object created with all fields as nil
       #
@@ -127,8 +221,8 @@ module Familia
         initialize_with_keyword_args(**kwargs)
       elsif args.any?
         initialize_with_positional_args(*args)
-      else
-        Familia.trace :INITIALIZE, dbclient, "#{self.class} initialized with no arguments", caller(1..1) if Familia.debug?
+      elsif Familia.debug?
+        Familia.trace :INITIALIZE, nil, "#{self.class} initialized with no arguments"
         # Default values are intentionally NOT set here
       end
 
@@ -138,16 +232,27 @@ module Familia
       init
     end
 
+    # Override this method in subclasses for custom initialization logic.
+    # This is called AFTER fields are set and relatives are initialized.
+    #
+    # DO NOT override initialize() - use this init() hook instead.
+    #
+    # Example:
+    #   def init(name = nil)
+    #     @name = name || SecureRandom.hex(4)
+    #   end
     def init(*args, **kwargs)
       # Default no-op
     end
 
     # Sets up related Database objects for the instance
-    # This method is crucial for establishing Redis-based relationships
+    # This method is crucial for establishing Valkey/Redis-based relationships
     #
     # This needs to be called in the initialize method.
     #
     def initialize_relatives
+      # Store initialization flag on singleton class to avoid polluting instance variables
+      return if singleton_class.instance_variable_defined?(:"@relatives_initialized")
       # Generate instances of each DataType. These need to be
       # unique for each instance of this class so they can piggyback
       # on the specifc index of this instance.
@@ -159,7 +264,7 @@ module Familia
       self.class.related_fields.each_pair do |name, data_type_definition|
         klass = data_type_definition.klass
         opts = data_type_definition.opts
-        Familia.trace :INITIALIZE_RELATIVES, dbclient, "#{name} => #{klass} #{opts.keys}", caller(1..1) if Familia.debug?
+        Familia.trace :INITIALIZE_RELATIVES, nil, "#{name} => #{klass} #{opts.keys}" if Familia.debug?
 
         # As a subclass of Familia::Horreum, we add ourselves as the parent
         # automatically. This is what determines the dbkey for DataType
@@ -169,7 +274,8 @@ module Familia
         #     then the dbkey for this DataType instance will be
         #     `customer:customer_id:name`.
         #
-        opts[:parent] = self # unless opts.key(:parent)
+        # Store reference to the instance for lazy ParentDefinition creation
+        opts[:parent] = self
 
         suffix_override = opts.fetch(:suffix, name)
 
@@ -186,49 +292,10 @@ module Familia
         # e.g. customer.name  #=> `#<Familia::HashKey:0x0000...>`
         instance_variable_set :"@#{name}", related_object
       end
-    end
 
-    # Initializes the object with positional arguments.
-    # Maps each argument to a corresponding field in the order they are defined.
-    #
-    # @param args [Array] List of values to be assigned to fields
-    # @return [Array<Symbol>] List of field names that were successfully updated
-    #   (i.e., had non-nil values assigned)
-    # @private
-    def initialize_with_positional_args(*args)
-      Familia.trace :INITIALIZE_ARGS, dbclient, args, caller(1..1) if Familia.debug?
-      self.class.fields.zip(args).filter_map do |field, value|
-        if value
-          send(:"#{field}=", value)
-          field.to_sym
-        end
-      end
+      # Mark relatives as initialized on singleton class to avoid polluting instance variables
+      singleton_class.instance_variable_set(:"@relatives_initialized", true)
     end
-    private :initialize_with_positional_args
-
-    # Initializes the object with keyword arguments.
-    # Assigns values to fields based on the provided hash of field names and values.
-    # Handles both symbol and string keys to accommodate different sources of data.
-    #
-    # @param fields [Hash] Hash of field names (as symbols or strings) and their values
-    # @return [Array<Symbol>] List of field names that were successfully updated
-    #   (i.e., had non-nil values assigned)
-    # @private
-    def initialize_with_keyword_args(**fields)
-      Familia.trace :INITIALIZE_KWARGS, dbclient, fields.keys, caller(1..1) if Familia.debug?
-      self.class.fields.filter_map do |field|
-        # Database will give us field names as strings back, but internally
-        # we use symbols. So we check for both.
-        value = fields[field.to_sym] || fields[field.to_s]
-        if value
-          # Use the mapped method name, not the field name
-          method_name = self.class.field_method_map[field] || field
-          send(:"#{method_name}=", value)
-          field.to_sym
-        end
-      end
-    end
-    private :initialize_with_keyword_args
 
     def initialize_with_keyword_args_deserialize_value(**fields)
       # Deserialize Database string values back to their original types
@@ -267,36 +334,28 @@ module Familia
                     send(definition)
                   when Proc
                     definition.call(self)
-                  end
+      end
 
       # Return nil for unpopulated identifiers (like unsaved ActiveRecord objects)
-      # Only raise errors when the identifier is actually needed for Redis operations
+      # Only raise errors when the identifier is actually needed for db operations
       return nil if unique_id.nil? || unique_id.to_s.empty?
 
       unique_id
     end
 
-    attr_writer :dbclient
-
-    # Summon the mystical Database connection from the depths of instance or class.
+    # Returns the Database connection for the instance using Chain of Responsibility pattern.
     #
-    # This method is like a magical divining rod, always pointing to the nearest
-    # source of Database goodness. It first checks if we have a personal Redis
-    # connection (@dbclient), and if not, it borrows the class's connection.
+    # This method uses a chain of handlers to resolve connections in priority order:
+    # 1. FiberTransactionHandler - Fiber[:familia_transaction] (active transaction)
+    # 2. CachedConnectionHandler - Accesses self.dbclient
+    # 3. CachedConnectionHandler - Accesses self.class.dbclient
+    # 4. GlobalFallbackHandler - Familia.dbclient(uri || logical_database) (global fallback)
     #
-    # @return [Redis] A shimmering Database connection, ready for your bidding.
+    # @return [Redis] the Database connection instance.
     #
-    # @example Finding your Database way
-    #   puts object.dbclient
-    #   # => #<Redis client v5.4.1 for redis://localhost:6379/0>
-    #
-    def dbclient
-      Fiber[:familia_transaction] || @dbclient || self.class.dbclient
-      # conn.select(self.class.logical_database)
-    end
 
     def generate_id
-      @objid ||= Familia.generate_id # rubocop:disable Naming/MemoizedInstanceVariableName
+      @objid ||= Familia.generate_id
     end
 
     # The principle is: **If Familia objects have `to_s`, then they should work
@@ -309,5 +368,49 @@ module Familia
 
       identifier.to_s
     end
+
+    private
+
+    # Initializes the object with positional arguments.
+    # Maps each argument to a corresponding field in the order they are defined.
+    #
+    # @param args [Array] List of values to be assigned to fields
+    # @return [Array<Symbol>] List of field names that were successfully updated
+    #   (i.e., had non-nil values assigned)
+    # @private
+    def initialize_with_positional_args(*args)
+      Familia.trace :INITIALIZE_ARGS, nil, args if Familia.debug?
+      self.class.fields.zip(args).filter_map do |field, value|
+        if value
+          send(:"#{field}=", value)
+          field.to_sym
+        end
+      end
+    end
+
+    # Initializes the object with keyword arguments.
+    # Assigns values to fields based on the provided hash of field names and values.
+    # Handles both symbol and string keys to accommodate different sources of data.
+    #
+    # @param fields [Hash] Hash of field names (as symbols or strings) and their values
+    # @return [Array<Symbol>] List of field names that were successfully updated
+    #   (i.e., had non-nil values assigned)
+    # @private
+    def initialize_with_keyword_args(**fields)
+      Familia.trace :INITIALIZE_KWARGS, nil, fields.keys if Familia.debug?
+      self.class.fields.filter_map do |field|
+        # Database will give us field names as strings back, but internally
+        # we use symbols. So we check for both.
+        value = fields[field.to_sym] || fields[field.to_s]
+        if value
+          # Use the mapped method name, not the field name
+          method_name = self.class.field_method_map[field] || field
+          send(:"#{method_name}=", value)
+          field.to_sym
+        end
+      end
+    end
+
+    # Builds the instance-level connection chain with handlers in priority order
   end
 end