familia 2.0.0.pre19 → 2.0.0.pre21

data/lib/familia/features/relationships/participation/participant_methods.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/relationships/participation/participant_methods.rb
+#
+# frozen_string_literal: true
 
 require_relative '../collection_operations'
 
@@ -8,37 +10,48 @@ module Familia
       # Methods added to PARTICIPANT classes (the ones calling participates_in)
       # These methods allow participant instances to manage their membership in target collections
       #
-      # Example: When Domain calls `participates_in Customer, :domains`
-      # Domain instances get methods to check/manage their presence in Customer collections
+      # Example: When Domain calls `participates_in Employee, :domains`
+      # Domain instances get methods to check/manage their presence in Employee collections
       module ParticipantMethods
         using Familia::Refinements::StylizeWords
         extend CollectionOperations
 
         # Visual Guide for methods added to PARTICIPANT instances:
         # =========================================================
-        # When Domain calls: participates_in Customer, :domains
+        # When Domain calls: participates_in Employee, :domains
         #
         # Domain instances (PARTICIPANT) get these methods:
-        # ├── in_customer_domains?(customer)              # Check if I'm in this customer's domains
-        # ├── add_to_customer_domains(customer, score)    # Add myself to customer's domains
-        # ├── remove_from_customer_domains(customer)      # Remove myself from customer's domains
-        # ├── score_in_customer_domains(customer)         # Get my score (sorted_set only)
-        # └── position_in_customer_domains(customer)      # Get my position (list only)
+        # ├── in_employee_domains?(employee)              # Check if I'm in this employee's domains
+        # ├── add_to_employee_domains(employee, score)    # Add myself to employee's domains
+        # ├── remove_from_employee_domains(employee)      # Remove myself from employee's domains
+        # ├── score_in_employee_domains(employee)         # Get my score (sorted_set only)
+        # └── position_in_employee_domains(employee)      # Get my position (list only)
         #
         # Note: To update scores, use the DataType API directly:
-        #   customer.domains.add(domain.identifier, new_score, xx: true)
-
+        #   employee.domains.add(domain.identifier, new_score, xx: true)
+        #
         module Builder
           extend CollectionOperations
 
           # Build all participant methods for a participation relationship
+          #
           # @param participant_class [Class] The class receiving these methods (e.g., Domain)
-          # @param target_class_name [String] Name of the target class (e.g., "Customer")
+          # @param target_class [Class, String] Target class object or 'class' for class-level participation (e.g., Employee or 'class')
           # @param collection_name [Symbol] Name of the collection (e.g., :domains)
           # @param type [Symbol] Collection type (:sorted_set, :set, :list)
-          def self.build(participant_class, target_class_name, collection_name, type)
-            # Convert to snake_case once for consistency (target_class_name is PascalCase)
-            target_name = target_class_name.to_s.snake_case
+          # @param as [Symbol, nil] Optional custom name for relationship methods (e.g., :employees)
+          #
+          def self.build(participant_class, target_class, collection_name, type, as)
+            # Determine target name based on participation context:
+            # - Instance-level: target_class is a Class object (e.g., Team) → use config_name ("project_team")
+            # - Class-level: target_class is the string 'class' (from class_participates_in) → use as-is
+            # The string 'class' is passed from TargetMethods.build_class_add_method when calling
+            # calculate_participation_score('class', collection_name) for class-level scoring
+            target_name = if target_class.is_a?(String)
+              target_class  # 'class' for class-level participation
+            else
+              target_class.config_name  # snake_case class name for instance-level
+            end
 
             # Core participant methods
             build_membership_check(participant_class, target_name, collection_name, type)
@@ -52,6 +65,110 @@ module Familia
             when :list
               build_position_method(participant_class, target_name, collection_name)
             end
+
+            # Build reverse collection methods on PARTICIPANT class for instance-level participation
+            # Skip for class-level participation because:
+            # - Class-level uses class_participates_in (e.g., User.all_users)
+            # - Bidirectional methods don't make sense: an individual User can't have "all_users"
+            # - Class-level collections are accessed directly on the class (User.all_users)
+            return if target_class.is_a?(String)  # 'class' indicates class-level participation
+
+            # If `as` is specified, create a custom method for just this collection
+            # Otherwise, add to the default pluralized method that unions all collections
+            if as
+              # Custom method for just this specific collection
+              build_reverse_collection_methods(participant_class, target_class, as, [collection_name])
+            else
+              # Default pluralized method - will include ALL collections for this target
+              build_reverse_collection_methods(participant_class, target_class, nil, nil)
+            end
+          end
+
+          # Generate reverse collection methods on participant class for bidirectional access
+          #
+          # Creates methods like:
+          # - user.team_instances (returns Array of Team instances)
+          # - user.team_ids (returns Array of IDs)
+          # - user.team? (returns Boolean)
+          # - user.team_count (returns Integer)
+          #
+          # @param participant_class [Class] The participant class (e.g., User)
+          # @param target_class [Class] The target class (e.g., Team)
+          # @param custom_name [Symbol, nil] Custom method name override (base name without suffix)
+          # @param collection_names [Array<Symbol>, nil] Specific collections to include (nil = all)
+          #
+          def self.build_reverse_collection_methods(participant_class, target_class, custom_name = nil, collection_names = nil)
+            # Determine base method name - either custom or target class config_name
+            # e.g., "project_team" or "contracting_org"
+            base_name = if custom_name
+              custom_name.to_s
+            else
+              # Use config_name as-is (e.g., "project_team")
+              target_class.config_name
+            end
+
+            # Store collection names as string array for matching
+            collections_filter = collection_names&.map(&:to_s)
+
+            # Generate the main collection method (e.g., user.project_team_instances)
+            #
+            # Loads actual objects - verifies Redis key existence via load_multi.
+            # No caching - load_multi is efficient enough and avoids stale data.
+            #
+            # @note Error Handling: This method lets database errors bubble up to the
+            #   application layer, consistent with Familia's error handling pattern.
+            #   Potential failures include:
+            #   - Familia::NotConnected - Redis connection unavailable
+            #   - Redis::TimeoutError - Operation timed out
+            #   - Redis::ConnectionError - Network/connection issues
+            #
+            #   For production environments, consider wrapping calls in application-level
+            #   error handling:
+            #
+            #   @example Application-level error handling
+            #     begin
+            #       teams = user.project_team_instances
+            #     rescue Familia::PersistenceError => e
+            #       # Handle database failure (log, fallback, retry, etc.)
+            #       Rails.logger.error("Failed to load teams: #{e.message}")
+            #       []  # Return empty array or other fallback
+            #     end
+            #
+            participant_class.define_method("#{base_name}_instances") do
+              ids = participating_ids_for_target(target_class, collections_filter)
+              # Use load_multi for Horreum objects (stored as Redis hashes)
+              target_class.load_multi(ids).compact
+            end
+
+            # Generate the IDs-only method (e.g., user.project_team_ids)
+            #
+            # Shallow - returns IDs from participation index without verifying key existence.
+            #
+            # @note Database errors (connection, timeout) will bubble up to caller.
+            #
+            participant_class.define_method("#{base_name}_ids") do
+              participating_ids_for_target(target_class, collections_filter)
+            end
+
+            # Generate the boolean check method (e.g., user.project_team?)
+            #
+            # Shallow check - verifies participation index membership, not Redis key existence.
+            #
+            # @note Database errors (connection, timeout) will bubble up to caller.
+            #
+            participant_class.define_method("#{base_name}?") do
+              participating_in_target?(target_class, collections_filter)
+            end
+
+            # Generate the count method (e.g., user.project_team_count)
+            #
+            # Shallow - counts IDs from participation index without verifying key existence.
+            #
+            # @note Database errors (connection, timeout) will bubble up to caller.
+            #
+            participant_class.define_method("#{base_name}_count") do
+              participating_ids_for_target(target_class, collections_filter).size
+            end
           end
 
           # Build method to check membership in target's collection

data/lib/familia/features/relationships/participation/rebuild_strategies.md

@@ -0,0 +1,41 @@
+## Indexes vs. Participations: Critical Distinction
+
+**Indexes are derived data** - they can be rebuilt from source:
+```ruby
+# Indexes derive from object fields and can be reconstructed
+User.rebuild_email_lookup  # Rebuilds from all User instances
+```
+
+**Participations are primary data** - they represent business decisions:
+```ruby
+# Participations are intentional relationships that must be explicitly created
+@team.add_members_instance(@user)  # Human/business decision about team membership
+```
+
+**Why this matters for rebuilding:**
+
+| Aspect | Indexes | Participations |
+|--------|---------|----------------|
+| **Source of truth** | Object field values | Business logic/user actions |
+| **Can rebuild?** | ✅ Yes - iterate instances | ❌ No - requires domain knowledge |
+| **Fix when wrong** | Run rebuild method | Re-apply business logic |
+| **Nature** | Computed/derived | Intentional/chosen |
+
+**Examples:**
+
+```ruby
+# ✅ INDEXES - Can rebuild because source exists
+User.rebuild_email_lookup      # Rebuilds from User.email field values
+company.rebuild_badge_index    # Rebuilds from Employee.badge_number values
+
+# ❌ PARTICIPATIONS - Cannot rebuild without knowing intent
+@team.members                  # Which users should be members? (business decision)
+@org.employees                 # Who works here? (HR/business logic)
+@project.contributors          # Who contributed? (tracked externally)
+
+# To fix participation data, reapply the business logic:
+correct_members.each { |user| @team.add_members_instance(user) }
+```
+
+**When indexes fail**, run the rebuild method.
+**When participations are wrong**, understand why they're wrong and reapply your application's business rules.

data/lib/familia/features/relationships/participation/target_methods.rb

@@ -1,4 +1,6 @@
 # lib/familia/features/relationships/participation/target_methods.rb
+#
+# frozen_string_literal: true
 
 require_relative '../collection_operations'
 
@@ -72,10 +74,9 @@ module Familia
           end
 
           # Build method to add an item to the collection
-          # Creates: customer.add_domain(domain, score)
+          # Creates: customer.add_domains_instance(domain, score)
           def self.build_add_item(target_class, collection_name, type)
-            singular_name = collection_name.to_s.singularize
-            method_name = "add_#{singular_name}"
+            method_name = "add_#{collection_name}_instance"
 
             target_class.define_method(method_name) do |item, score = nil|
               collection = send(collection_name)
@@ -105,10 +106,9 @@ module Familia
           end
 
           # Build method to remove an item from the collection
-          # Creates: customer.remove_domain(domain)
+          # Creates: customer.remove_domains_instance(domain)
           def self.build_remove_item(target_class, collection_name, type)
-            singular_name = collection_name.to_s.singularize
-            method_name = "remove_#{singular_name}"
+            method_name = "remove_#{collection_name}_instance"
 
             target_class.define_method(method_name) do |item|
               collection = send(collection_name)

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

@@ -1,6 +1,9 @@
 # lib/familia/features/relationships/participation.rb
+#
+# frozen_string_literal: true
 
 require_relative 'participation_relationship'
+require_relative 'participation_membership'
 require_relative 'collection_operations'
 require_relative 'participation/participant_methods'
 require_relative 'participation/target_methods'
@@ -160,10 +163,10 @@ module Familia
                                     type: :sorted_set, bidirectional: true)
             # Store metadata for this participation relationship
             participation_relationships << ParticipationRelationship.new(
-              target_class: self,
+              _original_target: self,   # For class-level, original and resolved are the same
+              target_class: self,       # The class itself
               collection_name: collection_name,
               score: score,
-
               type: type,
               bidirectional: bidirectional,
             )
@@ -176,7 +179,10 @@ module Familia
             # e.g., user.in_class_all_users?, user.add_to_class_all_users
             return unless bidirectional
 
-            ParticipantMethods::Builder.build(self, 'class', collection_name, type)
+            # Pass the string 'class' as target to distinguish class-level from instance-level
+            # This prevents generating reverse collection methods (user can't have "all_users")
+            # See ParticipantMethods::Builder.build for handling of this special case
+            ParticipantMethods::Builder.build(self, 'class', collection_name, type, nil)
           end
 
           # Define an instance-level participation relationship between two classes.
@@ -208,12 +214,14 @@ module Familia
           # all collections the instance belongs to. This enables efficient membership queries
           # and cleanup operations without scanning all possible collections.
           #
-          # @param target_class [Class, Symbol, String] The class that owns the collection. Can be:
-          #   - +Class+ object (e.g., +Customer+)
-          #   - +Symbol+ referencing class name (e.g., +:customer+, +:Customer+)
-          #   - +String+ class name (e.g., +"Customer"+)
-          # @param collection_name [Symbol] Name of the collection on the target class (e.g., +:domains+, +:members+)
-          # @param score [Symbol, Proc, Numeric, nil] Scoring strategy for sorted collections:
+          # @param target [Class, Symbol, String] The class that owns the collection. Can be:
+          #   - +Class+ object (e.g., +Employee+)
+          #   - +Symbol+ referencing class name (e.g., +:employee+, +:Employee+)
+          #   - +String+ class name (e.g., +"Employee"+)
+          # @param collection_name [Symbol] Name of the collection on the
+          #        target class (e.g., +:domains+, +:members+)
+          # @param score [Symbol, Proc, Numeric, nil] Scoring strategy for
+          #        sorted collections:
           #   - +Symbol+: Field name or method name (e.g., +:priority+, +:created_at+)
           #   - +Proc+: Dynamic calculation executed in participant instance context
           #   - +Numeric+: Static score applied to all participants
@@ -221,17 +229,24 @@ module Familia
           #   - +:remove+: Remove from all collections on destruction (default)
           #   - +:ignore+: Leave in collections when destroyed
           # @param type [Symbol] Valkey/Redis collection type:
-          #   - +:sorted_set+: Ordered by score, allows duplicates with different scores (default)
+          #   - +:sorted_set+: Ordered by score, allows duplicates with
+          #        different scores (default)
           #   - +:set+: Unordered unique membership
           #   - +:list+: Ordered sequence, allows duplicates
-          # @param bidirectional [Boolean] Whether to generate convenience methods on participant class (default: +true+)
+          # @param bidirectional [Boolean] Whether to generate reverse collection
+          #        methods on participant class. If true, methods are generated using the
+          #        name of the target class. (default: +true+)
+          # @param as [Symbol, nil] Custom name for reverse collection methods
+          #        (e.g., +as: :contracting_orgs+). When provided, overrides the default
+          #        method name derived from the target class.
+          #
+          # @example Basic domain-employee relationship
           #
-          # @example Basic domain-customer relationship
           #   class Domain < Familia::Horreum
           #     field :name
           #     field :created_at
           #
-          #     participates_in Customer, :domains, score: :created_at
+          #     participates_in Employee, :domains, score: :created_at
           #   end
           #
           #   # Usage:
@@ -241,6 +256,7 @@ module Familia
           #   domain.current_participations             # All collections domain belongs to
           #
           # @example Multi-collection participation with different types
+          #
           #   class Employee < Familia::Horreum
           #     field :hire_date
           #     field :skill_level
@@ -267,42 +283,54 @@ module Familia
           # @see #class_participates_in for class-level participation
           # @see ModelInstanceMethods#current_participations for membership queries
           # @see ModelInstanceMethods#calculate_participation_score for scoring details
-          # @since 1.0.0
-          def participates_in(target_class, collection_name, score: nil,
-                              type: :sorted_set, bidirectional: true)
-            # Handle class target using Familia.resolve_class
-            resolved_class = Familia.resolve_class(target_class)
+          #
+          def participates_in(target, collection_name, score: nil, type: :sorted_set, bidirectional: true, as: nil)
+
+            # Normalize the target class parameter
+            target_class = Familia.resolve_class(target)
+
+            # Raise helpful error if target class can't be resolved
+            if target_class.nil?
+              raise ArgumentError, <<~ERROR
+                Cannot resolve target class: #{target.inspect}
+
+                The target class '#{target}' could not be found in Familia.members.
+                This usually means:
+                1. The target class hasn't been loaded/required yet (load order issue)
+                2. The target class name is misspelled
+                3. The target class doesn't inherit from Familia::Horreum
+
+                Current registered classes: #{Familia.members.filter_map(&:name).sort.join(', ')}
+
+                Solution: Ensure #{target} is defined and loaded before #{self.name}
+              ERROR
+            end
 
             # Store metadata for this participation relationship
             participation_relationships << ParticipationRelationship.new(
-              target_class: target_class, # as passed to `participates_in`
+              _original_target: target,      # Original value as passed (Symbol/String/Class)
+              target_class: target_class,    # Resolved Class object
               collection_name: collection_name,
               score: score,
-
               type: type,
               bidirectional: bidirectional,
             )
 
-            # Resolve target class if it's a symbol/string
-            actual_target_class = if target_class.is_a?(Class)
-              target_class
-            else
-              Familia.member_by_config_name(target_class)
-            end
-
             # STEP 0: Add participations tracking field to PARTICIPANT class (Domain)
-            # This creates the proper key: "domain:123:participations" (not "domain:123:object:participations")
+            # This creates the proper key: "domain:123:participations"
             set :participations unless method_defined?(:participations)
 
-            # STEP 1: Add collection management methods to TARGET class (Customer)
-            # Customer gets: domains, add_domain, remove_domain, etc.
-            TargetMethods::Builder.build(actual_target_class, collection_name, type)
+            # STEP 1: Add collection management methods to TARGET class (Employee)
+            # Employee gets: domains, add_domain, remove_domain, etc.
+            TargetMethods::Builder.build(target_class, collection_name, type)
 
-            # STEP 2: Add participation methods to PARTICIPANT class (Domain) - only if bidirectional
-            # Domain gets: in_customer_domains?, add_to_customer_domains, etc.
-            return unless bidirectional
-
-            ParticipantMethods::Builder.build(self, resolved_class.familia_name, collection_name, type)
+            # STEP 2: Add participation methods to PARTICIPANT class (Domain) - only if
+            # bidirectional. e.g. in_employee_domains?, add_to_employee_domains, etc.
+            if bidirectional
+              # `as` parameter allows custom naming for reverse collections
+              # If not provided, we'll let the builder use the pluralized target class name
+              ParticipantMethods::Builder.build(self, target_class, collection_name, type, as)
+            end
           end
 
           # Get all participation relationships defined for this class.
@@ -365,6 +393,8 @@ module Familia
           # within scoring Procs.
           #
           # @param target_class [Class, Symbol, String] The target class containing the collection
+          #   - For instance-level participation: Class object (e.g., +Project+, +Team+)
+          #   - For class-level participation: The string +'class'+ (from +class_participates_in+)
           # @param collection_name [Symbol] The collection name within the target class
           # @return [Float] Calculated score for sorted set positioning, falls back to current_score
           #
@@ -402,18 +432,9 @@ module Familia
           # @see #track_participation_in for reverse index management
           # @since 1.0.0
           def calculate_participation_score(target_class, collection_name)
-            # Find the participation configuration with robust type comparison
+            # Find the participation configuration using the new matches? method
             participation_config = self.class.participation_relationships.find do |details|
-              # Normalize both sides for comparison to handle Class, Symbol, and String types
-              config_target = details.target_class
-              config_target = config_target.name if config_target.is_a?(Class)
-              config_target = config_target.to_s
-
-              comparison_target = target_class
-              comparison_target = comparison_target.name if comparison_target.is_a?(Class)
-              comparison_target = comparison_target.to_s
-
-              config_target == comparison_target && details.collection_name == collection_name
+              details.matches?(target_class, collection_name)
             end
 
             return current_score unless participation_config
@@ -542,6 +563,69 @@ module Familia
           # @see #track_participation_in for reverse index management
           # @see #calculate_participation_score for scoring details
           # @since 1.0.0
+          # Get all IDs where this instance participates for a specific target class
+          #
+          # This is a shallow check - it extracts IDs from the participation index without
+          # verifying that the target Redis keys actually exist. Use this for fast ID
+          # enumeration; use *_instances methods if you need existence verification.
+          #
+          # Optimized to iterate through keys once and use Set for efficient uniqueness,
+          # reducing string operations and object allocations.
+          #
+          # @param target_class [Class] The target class to filter by
+          # @param collection_names [Array<String>, nil] Optional collection name filter
+          # @return [Array<String>] Array of unique target instance IDs
+          def participating_ids_for_target(target_class, collection_names = nil)
+
+            # Use config_name to get the proper snake_case format (e.g., "project_team")
+            target_prefix = "#{target_class.config_name}#{Familia.delim}"
+            ids = Set.new
+
+            participations.members.each do |key|
+              next unless key.start_with?(target_prefix)
+
+              parts = key.split(Familia.delim, 3)  # Split into ["targetclass", "id", "collection"]
+              id = parts[1]
+
+              # If filtering by collection names, check before adding
+              if collection_names && !collection_names.empty?
+                collection = parts[2]
+                ids << id if collection_names.include?(collection)
+              else
+                ids << id
+              end
+            end
+
+            ids.to_a
+          end
+
+          # Check if this instance participates in any target of a specific class
+          #
+          # This is a shallow check - it only verifies that participation entries exist
+          # in the participation index. It does NOT verify that the target Redis keys
+          # actually exist. Use this for fast membership checks.
+          #
+          # Optimized to stop scanning as soon as a match is found.
+          #
+          # @param target_class [Class] The target class to check
+          # @param collection_names [Array<String>, nil] Optional collection name filter
+          # @return [Boolean] true if any matching participation exists
+          def participating_in_target?(target_class, collection_names = nil)
+            target_prefix = "#{target_class.config_name}#{Familia.delim}"
+
+            participations.members.any? do |key|
+              next false unless key.start_with?(target_prefix)
+
+              # If filtering by specific collections, check the collection name
+              if collection_names && !collection_names.empty?
+                collection = key.split(Familia.delim, 3)[2]
+                collection_names.include?(collection)
+              else
+                true
+              end
+            end
+          end
+
           def current_participations
             return [] unless self.class.respond_to?(:participation_relationships)
 
@@ -555,59 +639,61 @@ module Familia
             collection_keys.each do |collection_key|
               # Parse the collection key to extract target info
               # Expected format: "targetclass:targetid:collectionname"
-              key_parts = collection_key.split(':')
-              next unless key_parts.length >= 3
-
-              target_class_config = key_parts[0]
-              target_id = key_parts[1]
-              collection_name_from_key = key_parts[2]
+              target_class_config, target_id, collection_name_from_key = collection_key.split(Familia.delim, 3)
+              next unless target_class_config && target_id && collection_name_from_key
 
               # Find the matching participation configuration
               # Note: target_class_config from key is snake_case
               config = self.class.participation_relationships.find do |cfg|
-                cfg.target_class_config_name == target_class_config &&
+                cfg.target_class.config_name == target_class_config &&
                   cfg.collection_name.to_s == collection_name_from_key
               end
 
               next unless config
 
               # Find the target instance and check membership using Horreum DataTypes
+              # config.target_class is already a resolved Class object
               begin
-                target_class = Familia.resolve_class(config.target_class)
-                target_instance = target_class.find_by_id(target_id)
+                target_instance = config.target_class.find_by_id(target_id)
                 next unless target_instance
 
                 # Use Horreum's DataType accessor to get the collection
                 collection = target_instance.send(config.collection_name)
 
-                # Check membership using DataType methods
-                membership_data = {
-                  target_class: config.target_class.familia_name,
-                  target_id: target_id,
-                  collection_name: config.collection_name,
-                  type: config.type,
-                }
+                # Check membership using DataType methods and build ParticipationMembership
+                score = nil
+                decoded_score = nil
+                position = nil
 
                 case config.type
                 when :sorted_set
                   score = collection.score(identifier)
                   next unless score
 
-                  membership_data[:score] = score
-                  membership_data[:decoded_score] = decode_score(score) if respond_to?(:decode_score)
+                  decoded_score = decode_score(score) if respond_to?(:decode_score)
                 when :set
                   is_member = collection.member?(identifier)
                   next unless is_member
                 when :list
                   position = collection.to_a.index(identifier)
                   next unless position
-
-                  membership_data[:position] = position
                 end
 
-                memberships << membership_data
+                # Create ParticipationMembership instance
+                # Use target_class_base to get clean class name without namespace
+                membership = ParticipationMembership.new(
+                  target_class: config.target_class_base,
+                  target_id: target_id,
+                  collection_name: config.collection_name,
+                  type: config.type,
+                  score: score,
+                  decoded_score: decoded_score,
+                  position: position
+                )
+
+                memberships << membership
               rescue StandardError => e
-                Familia.ld "[#{collection_key}] Error checking membership: #{e.message}"
+                Familia.debug "[#{collection_key}] Error checking membership: #{e.message}"
                 next
               end
             end