familia 2.0.0.pre15 → 2.0.0.pre17

data/lib/familia/features/object_identifier.rb

@@ -8,7 +8,7 @@ module Familia
     #
     # Object identifiers are:
     # - Unique across the system
-    # - Persistent (stored in Redis/Valkey)
+    # - Persistent (stored in Valkey/Redis)
     # - Lazily generated (only when first accessed)
     # - Configurable (multiple generation strategies available)
     # - Preserved during initialization (existing IDs never regenerated)
@@ -50,7 +50,7 @@ module Familia
     #
     #   # Custom generation strategy
     #   class TimestampedItem < Familia::Horreum
-    #     feature :object_identifier, generator: -> { "item_#{Time.now.to_i}_#{SecureRandom.hex(4)}" }
+    #     feature :object_identifier, generator: -> { "item_#{Familia.now.to_i}_#{SecureRandom.hex(4)}" }
     #     field :data
     #   end
     #
@@ -60,9 +60,9 @@ module Familia
     # Data Integrity Guarantees:
     #
     # The feature preserves the object identifier passed during initialization,
-    # ensuring that existing objects loaded from Redis maintain their IDs:
+    # ensuring that existing objects loaded from Valkey/Redis maintain their IDs:
     #
-    #   # Loading existing object from Redis preserves ID
+    #   # Loading existing object from Valkey/Redis preserves ID
     #   existing = User.new(objid: 'existing-uuid-value', email: 'existing@example.com')
     #   existing.objid  # => "existing-uuid-value" (preserved, not regenerated)
     #
@@ -71,7 +71,7 @@ module Familia
     # - Lazy Generation: IDs generated only when first accessed
     # - Thread-Safe: Generator strategy configured once during initialization
     # - Memory Efficient: No unnecessary ID generation for unused objects
-    # - Redis Efficient: Only persists non-nil values to conserve memory
+    # - Valkey/Redis Efficient: Only persists non-nil values to conserve memory
     #
     # Security Considerations:
     #
@@ -86,12 +86,22 @@ module Familia
       DEFAULT_GENERATOR = :uuid_v7
 
       def self.included(base)
-        Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
-        base.extend ClassMethods
+        Familia.trace :LOADED, self, base if Familia.debug?
+        base.extend ModelClassMethods
+        base.include ModelInstanceMethods
 
         # Ensure default generator is set in feature options
         base.add_feature_options(:object_identifier, generator: DEFAULT_GENERATOR)
 
+        # Add class-level mapping for objid -> id lookups.
+        #
+        # If the model uses objid as it's primary key, this mapping will be
+        # redundant to the builtin functionality of horreum clases, that
+        # automatically populate ModelClass.instances sorted set. However,
+        # if the model uses any other field as primary key, this mapping
+        # is necessary to lookup objects by their objid.
+        base.class_hashkey :objid_lookup
+
         # Register the objid field using a simple custom field type
         base.register_field_type(ObjectIdentifierFieldType.new(:objid, as: :objid, fast_method: false))
       end
@@ -101,7 +111,7 @@ module Familia
       # Object identifier fields automatically generate unique identifiers when first
       # accessed if not already set. The generation strategy is configurable via
       # feature options. These fields preserve any values set during initialization
-      # to ensure data integrity when loading existing objects from Redis.
+      # to ensure data integrity when loading existing objects from the database.
       #
       # The field type tracks the generator used for each objid to provide provenance
       # information for security-sensitive operations like external identifier generation.
@@ -166,7 +176,7 @@ module Familia
         # Override setter to preserve values during initialization
         #
         # This ensures that values passed during object initialization
-        # (e.g., when loading from Redis) are preserved and not overwritten
+        # (e.g., when loading from Valkey/Redis) are preserved and not overwritten
         # by the lazy generation logic.
         #
         # @param klass [Class] The class to define the method on
@@ -177,13 +187,20 @@ module Familia
 
           handle_method_conflict(klass, :"#{method_name}=") do
             klass.define_method :"#{method_name}=" do |value|
+              # Remove old mapping if objid is changing
+              old_value = instance_variable_get(:"@#{field_name}")
+              if old_value && old_value != value
+                Familia.logger.info("Removing objid mapping for #{old_value}")
+                self.class.objid_lookup.remove_field(old_value)
+              end
+
               instance_variable_set(:"@#{field_name}", value)
 
-              # When setting objid from external source (e.g., loading from Redis),
-              # we cannot determine the original generator, so we clear the provenance
-              # tracking to indicate unknown origin. This prevents false assumptions
-              # about the security properties of externally-provided identifiers.
-              instance_variable_set(:"@#{field_name}_generator_used", nil)
+              # When setting objid from external source (e.g., loading from Valkey/Redis),
+              # infer the generator type from the format to restore provenance tracking.
+              # This allows features like ExternalIdentifier to work correctly on loaded objects.
+              inferred_generator = infer_objid_generator(value)
+              instance_variable_set(:"@#{field_name}_generator_used", inferred_generator)
             end
           end
         end
@@ -205,7 +222,7 @@ module Familia
         end
       end
 
-      module ClassMethods
+      module ModelClassMethods
         # Generate a new object identifier using the configured strategy
         #
         # @return [String] A new unique identifier
@@ -220,7 +237,7 @@ module Familia
           when :uuid_v4
             SecureRandom.uuid_v4
           when :hex
-            Familia.generate_hex_id
+            Familia.generate_id(16)
           when Proc
             generator.call
           else
@@ -243,18 +260,73 @@ module Familia
 
           if Familia.debug?
             reference = caller(1..1).first
-            Familia.trace :FIND_BY_OBJID, Familia.dbclient, objid, reference
+            Familia.trace :FIND_BY_OBJID, nil, objid, reference
           end
 
-          # Use the object identifier as the key for lookup
-          # This is a simple stub implementation - would need more sophisticated
-          # search logic in a real application
-          find_by_id(objid)
+          # Look up the primary ID from the external ID mapping
+          primary_id = objid_lookup[objid]
+
+          # If there is no mapping for this instance's objid, perhaps
+          # the object dbkey is already using the objid.
+          primary_id = objid if primary_id.nil?
+
+          find_by_id(primary_id)
         rescue Familia::NotFound
+          # If the object was deleted but mapping wasn't cleaned up
+          # we could autoclean here, as long as we log it.
+          # objid_lookup.remove_field(objid)
           nil
         end
       end
 
+      # Instance methods for object identifier management
+      module ModelInstanceMethods
+        # Override save to update objid_lookup mapping
+        #
+        # This ensures the objid_lookup index is populated during save operations
+        # rather than during object initialization, preventing unwanted database
+        # writes when calling .new()
+        #
+        # @param update_expiration [Boolean] Whether to update key expiration
+        # @return [Boolean] True if save was successful
+        #
+        def save(update_expiration: true)
+          result = super
+
+          # Update objid_lookup mapping after successful save
+          if result && respond_to?(:objid) && respond_to?(:identifier)
+            current_objid = objid  # Triggers lazy generation if needed
+            if current_objid && identifier
+              self.class.objid_lookup[current_objid] = identifier
+            end
+          end
+
+          result
+        end
+
+        # Override save_if_not_exists to update objid_lookup mapping
+        #
+        # This ensures the objid_lookup index is populated during create operations
+        # which use save_if_not_exists instead of save.
+        #
+        # @param update_expiration [Boolean] Whether to update key expiration
+        # @return [Boolean] True if save was successful
+        #
+        def save_if_not_exists(update_expiration: true)
+          result = super
+
+          # Update objid_lookup mapping after successful save
+          if result && respond_to?(:objid) && respond_to?(:identifier)
+            current_objid = objid  # Triggers lazy generation if needed
+            if current_objid && identifier
+              self.class.objid_lookup[current_objid] = identifier
+            end
+          end
+
+          result
+        end
+      end
+
       # Instance method for generating object identifier using configured strategy
       #
       # This method is called by the ObjectIdentifierFieldType when lazy generation
@@ -275,14 +347,52 @@ module Familia
         objid
       end
 
-      # Full-length alias setter for objid
+      # Infers the generator type (:uuid_v7, :uuid_v4, :hex) from the format of an objid string.
       #
-      # @param value [String] The object identifier to set
+      # This method analyzes the objid format to restore provenance tracking when loading
+      # objects from Redis, allowing dependent features like ExternalIdentifier to work correctly.
       #
+      # @param objid_value [String] The objid string to analyze
+      # @return [Symbol, nil] The inferred generator type or nil if unknown
+      def infer_objid_generator(objid_value)
+        return nil if objid_value.nil? || objid_value.to_s.empty?
+
+        objid_str = objid_value.to_s
+
+        # UUID format: xxxxxxxx-xxxx-Vxxx-xxxx-xxxxxxxxxxxx (36 chars with hyphens)
+        # where V is the version nibble at position 14
+        if objid_str.length == 36 && objid_str[8] == '-' && objid_str[13] == '-' && objid_str[18] == '-' && objid_str[23] == '-'
+          version_char = objid_str[14]
+          case version_char
+          when '7'
+            :uuid_v7
+          when '4'
+            :uuid_v4
+          else
+            nil # Unknown UUID version
+          end
+        # Hex format: pure hexadecimal without hyphens (32 or 64 chars typically)
+        elsif objid_str.match?(/\A[0-9a-fA-F]+\z/)
+          :hex
+        else
+          nil # Unknown format
+        end
+      end
+      private :infer_objid_generator
+
       def object_identifier=(value)
         self.objid = value
       end
 
+      def destroy!
+        # Clean up objid mapping when object is destroyed
+        current_objid = instance_variable_get(:@objid)
+
+        self.class.objid_lookup.remove_field(current_objid) if current_objid
+
+        super if defined?(super)
+      end
+
       # Initialize object identifier configuration
       #
       # Called during object initialization to set up the ID generation strategy.
@@ -300,9 +410,8 @@ module Familia
 
         options = self.class.feature_options(:object_identifier)
         generator = options[:generator] || DEFAULT_GENERATOR
-        Familia.trace :OBJID_INIT, dbclient, "Generator strategy: #{generator}", caller(1..1)
+        Familia.trace :OBJID_INIT, nil, "Generator strategy: #{generator}"
       end
-
     end
   end
 end

data/lib/familia/features/quantization.rb

@@ -106,7 +106,7 @@ module Familia
     #       activity.save
     #     end
     #
-    #     def self.activity_for_hour(time = Time.now)
+    #     def self.activity_for_hour(time = Familia.now)
     #       bucket_id = "activity:#{qstamp(1.hour, time: time, pattern: '%Y%m%d%H')}"
     #       find(bucket_id)
     #     end
@@ -129,7 +129,7 @@ module Familia
     #             interval: interval.to_i)
     #       end
     #
-    #       metric.data_points.add(timestamp, value)
+    #       metric.data_points.add(value, timestamp)
     #       metric.timestamp = timestamp
     #       metric.value = value
     #       metric.save
@@ -175,13 +175,13 @@ module Familia
     #
     #     def self.utc_hourly_key(metric_name)
     #       # Always use UTC for consistent global buckets
-    #       timestamp = qstamp(1.hour, time: Time.now.utc, pattern: '%Y%m%d%H')
+    #       timestamp = qstamp(1.hour, time: Familia.now, pattern: '%Y%m%d%H')
     #       "global:#{metric_name}:#{timestamp}"
     #     end
     #
     #     def self.local_daily_key(metric_name, timezone = 'America/New_York')
     #       # Use local timezone for region-specific buckets
-    #       local_time = Time.now.in_time_zone(timezone)
+    #       local_time = Familia.now.in_time_zone(timezone)
     #       timestamp = qstamp(1.day, time: local_time, pattern: '%Y%m%d')
     #       "#{timezone.gsub('/', '_')}:#{metric_name}:#{timestamp}"
     #     end
@@ -194,7 +194,7 @@ module Familia
     #
     #     # Cache quantized timestamps to avoid repeated calculations
     #     def self.cached_qstamp(quantum, pattern: nil, time: nil)
-    #       cache_key = "qstamp:#{quantum}:#{pattern}:#{(time || Time.now).to_i / quantum}"
+    #       cache_key = "qstamp:#{quantum}:#{pattern}:#{(time || Familia.now).to_i / quantum}"
     #       Rails.cache.fetch(cache_key, expires_in: quantum) do
     #         qstamp(quantum, pattern: pattern, time: time)
     #       end
@@ -245,19 +245,18 @@ module Familia
     #   NoDefault.qstamp()  # Uses 10.minutes as fallback quantum
     #
     module Quantization
-
       Familia::Base.add_feature self, :quantization
 
       using Familia::Refinements::TimeLiterals
 
       def self.included(base)
-        Familia.trace :LOADED, self, base, caller(1..1) if Familia.debug?
-        base.extend ClassMethods
+        Familia.trace :LOADED, self, base if Familia.debug?
+        base.extend ModelClassMethods
       end
 
-      # Familia::Quantization::ClassMethods
+      # Familia::Quantization::ModelClassMethods
       #
-      module ClassMethods
+      module ModelClassMethods
         # Generates a quantized timestamp based on the given parameters
         #
         # This method rounds the current time to the nearest quantum and optionally
@@ -286,9 +285,7 @@ module Familia
         #
         def qstamp(quantum = nil, pattern: nil, time: nil)
           # Handle array input format: [quantum, pattern]
-          if quantum.is_a?(Array)
-            quantum, pattern = quantum
-          end
+          quantum, pattern = quantum if quantum.is_a?(Array)
 
           # Use default quantum if none specified
           # Priority: provided quantum > class default_expiration > 10.minutes fallback
@@ -323,11 +320,11 @@ module Familia
           end_bucket = qstamp(quantum, time: end_time)
 
           while current <= end_bucket
-            if pattern
-              timestamps << Time.at(current).strftime(pattern)
-            else
-              timestamps << current
-            end
+            timestamps << if pattern
+                            Time.at(current).strftime(pattern)
+                          else
+                            current
+                          end
             current += quantum
           end
 
@@ -352,7 +349,7 @@ module Familia
           bucket_start = qstamp(quantum, time: Time.at(bucket_time))
           bucket_end = bucket_start + quantum - 1
 
-          timestamp >= bucket_start && timestamp <= bucket_end
+          timestamp.between?(bucket_start, bucket_end)
         end
       end
 
@@ -397,8 +394,6 @@ module Familia
         base_id = respond_to?(:identifier) ? identifier : object_id
         "#{base_id}#{separator}#{timestamp}"
       end
-
-      extend ClassMethods
     end
   end
 end

data/lib/familia/features/relationships/README.md

@@ -0,0 +1,97 @@
+<!--lib/familia/features/relationships/README.md-->
+
+## Core Modules
+
+**relationships.rb** - Main orchestrator that unifies all relationship functionality into a single feature, providing the public API and coordinating between all submodules.
+
+**indexing.rb** - O(1) lookup capability via Valkey/Redis hashes and sets. Enables fast field-based searches when parent-scoped (within: ParentClass). Creates instance methods on parent class for scoped lookups.
+
+**participation.rb** - Multi-presence management where objects can exist in multiple collections simultaneously with score-encoded metadata (timestamps, permissions, etc.). All add/remove operations use transactions for atomicity.
+
+## Quick API Guide
+
+**participates_in** - Collection membership ("this object belongs in that collection")
+```ruby
+participates_in Organization, :members, score: :joined_at, bidirectional: true
+# Creates: org.members, org.add_member(), customer.add_to_organization_members()
+```
+
+**unique_index** - Fast unique lookups ("find object by unique field value")
+```ruby
+unique_index :email, :email_index, within: Organization  # Scoped: org.find_by_email()
+```
+
+**multi_index** - Fast multi-value lookups ("find all objects by field value")
+```ruby
+multi_index :department, :dept_index, within: Organization
+# Creates: org.sample_from_department(), org.find_all_by_department()
+```
+
+## Key Philosophy
+
+The entire system embraces "where does this appear?" rather than "who owns this?" - enabling objects to exist in multiple contexts simultaneously while maintaining fast lookups and atomic operations.
+
+## When to Use Which
+
+<details>
+<summary>📋 participates_in vs indexing - Decision Guide</summary>
+
+### participates_in - Collection Membership
+- **Purpose**: "This object belongs in that collection"
+- **Storage**: SortedSet/Set/List of object IDs with optional scores
+- **Use for**: Membership relationships, ordered lists, scored collections
+- **Example**: Customers in an Organization, Tasks in a Project
+- **Atomicity**: Transactions for all operations (collection + reverse index)
+
+```ruby
+participates_in Organization, :members, score: :joined_at
+# Creates: org.members (SortedSet), org.add_member(), customer.add_to_organization_members()
+```
+
+### unique_index - Fast Unique Lookups
+- **Purpose**: "Find THE object by unique field value"
+- **Storage**: HashKey for O(1) field-to-object mapping
+- **Use for**: Email lookups, username searches, unique IDs
+- **Example**: Find customer by email, find employee by badge number
+- **Atomicity**: Transactions for updates (remove old + add new)
+
+```ruby
+unique_index :email, :email_index, within: Organization
+# Creates: org.find_by_email(), org.find_all_by_email()
+```
+
+### multi_index - Fast Multi-Value Lookups
+- **Purpose**: "Find ALL objects by shared field value"
+- **Storage**: UnsortedSet for O(1) field-to-objects mapping
+- **Use for**: Grouping by department, status, category, tags
+- **Example**: All employees in a department, all tasks with status
+- **Atomicity**: Transactions for updates (remove from old set + add to new set)
+
+```ruby
+multi_index :department, :dept_index, within: Organization
+# Creates: org.sample_from_department(dept, count), org.find_all_by_department(dept)
+```
+
+</details>
+
+> [!NOTE]
+> **Scoping Patterns**: `unique_index` and `multi_index` use the `within:` parameter for instance-scoping, while participation uses distinct method names (`participates_in` vs `class_participates_in`) to reflect fundamentally different semantics (instance collections vs auto-tracking all instances).
+
+> [!TIP]
+> **Quick Decision Guide**
+> - Need to store a collection of objects? → `participates_in`
+> - Need to find ONE object by unique field? → `unique_index`
+> - Need to find MANY objects by shared field? → `multi_index`
+> - Combination? → Use all three together (very common)
+
+```ruby
+class Customer < Familia::Horreum
+  feature :relationships
+
+  participates_in Organization, :members    # Customer belongs to org
+  unique_index :email, :email_index, within: Organization  # Find by unique email
+end
+```
+
+> [!NOTE]
+> **Key**: `participates_in` = collections, `unique_index` = unique lookups, `multi_index` = group lookups.

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

@@ -0,0 +1,104 @@
+# lib/familia/features/relationships/collection_operations.rb
+
+module Familia
+  module Features
+    module Relationships
+      # Shared collection operations for Participation module
+      # Provides common methods for working with Horreum-managed DataType collections
+      # Used by both ParticipantMethods and TargetMethods to reduce duplication
+      module CollectionOperations
+        using Familia::Refinements::StylizeWords
+
+        # Ensure a target class has the specified DataType field defined
+        # @param target_class [Class] The class that should have the collection
+        # @param collection_name [Symbol] Name of the collection field
+        # @param type [Symbol] Collection type (:sorted_set, :set, :list)
+        def ensure_collection_field(target_class, collection_name, type)
+          return if target_class.method_defined?(collection_name)
+
+          target_class.send(type, collection_name)
+        end
+
+        # Add an item to a collection, handling type-specific operations
+        # @param collection [Familia::DataType] The collection to add to
+        # @param item [Object] The item to add (must respond to identifier)
+        # @param score [Float, nil] Score for sorted sets
+        # @param type [Symbol] Collection type
+        def add_to_collection(collection, item, type:, score: nil, target_class: nil, collection_name: nil)
+          case type
+          when :sorted_set
+            # Ensure score is never nil for sorted sets
+            score ||= calculate_item_score(item, target_class, collection_name)
+            collection.add(item.identifier, score)
+          when :list
+            # Lists use push/unshift operations
+            collection.add(item.identifier)
+          when :set
+            # Sets use simple add
+            collection.add(item.identifier)
+          else
+            raise ArgumentError, "Unknown collection type: #{type}"
+          end
+        end
+
+        # Remove an item from a collection
+        # @param collection [Familia::DataType] The collection to remove from
+        # @param item [Object] The item to remove (must respond to identifier)
+        # @param type [Symbol] Collection type
+        def remove_from_collection(collection, item, type: nil)
+          # All collection types support remove/delete
+          collection.remove(item.identifier)
+        end
+
+        # Check if an item is a member of a collection
+        # @param collection [Familia::DataType] The collection to check
+        # @param item [Object] The item to check (must respond to identifier)
+        # @return [Boolean] True if item is in collection
+        def member_of_collection?(collection, item)
+          collection.member?(item.identifier)
+        end
+
+        # Bulk add items to a collection using DataType methods
+        # @param collection [Familia::DataType] The collection to add to
+        # @param items [Array] Array of items to add
+        # @param type [Symbol] Collection type
+        def bulk_add_to_collection(collection, items, type:, target_class: nil, collection_name: nil)
+          return if items.empty?
+
+          case type
+          when :sorted_set
+            # Add items one by one for sorted sets to ensure proper scoring
+            items.each do |item|
+              score = calculate_item_score(item, target_class, collection_name)
+              collection.add(item.identifier, score)
+            end
+          when :set, :list
+            # For sets and lists, add items one by one using DataType methods
+            items.each do |item|
+              collection.add(item.identifier)
+            end
+          else
+            raise ArgumentError, "Unknown collection type: #{type}"
+          end
+        end
+
+        private
+
+        # Calculate score for an item
+        # @param item [Object] The item to score
+        # @param target_class [Class, nil] The target class for participation scoring
+        # @param collection_name [Symbol, nil] The collection name for participation scoring
+        # @return [Float] The calculated score
+        def calculate_item_score(item, target_class = nil, collection_name = nil)
+          if item.respond_to?(:calculate_participation_score) && target_class && collection_name
+            item.calculate_participation_score(target_class, collection_name)
+          elsif item.respond_to?(:current_score)
+            item.current_score
+          else
+            Familia.now.to_f
+          end
+        end
+      end
+    end
+  end
+end