familia 2.0.0.pre22 → 2.0.0.pre23

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

@@ -0,0 +1,150 @@
+# lib/familia/features/relationships/participation/through_model_operations.rb
+#
+# frozen_string_literal: true
+
+module Familia
+  module Features
+    module Relationships
+      module Participation
+        # ThroughModelOperations provides lifecycle management for through models
+        # in participation relationships.
+        #
+        # Through models implement the join table pattern, creating an intermediate
+        # object between target and participant that can carry additional attributes
+        # (e.g., role, permissions, metadata).
+        #
+        # Key characteristics:
+        # - Deterministic identifier: Built from target, participant, and through class
+        # - Auto-lifecycle: Created on add, destroyed on remove
+        # - Idempotent: Re-adding updates existing model
+        # - Atomic: All operations use transactions
+        # - Cache-friendly: Auto-updates updated_at for invalidation
+        #
+        # Example:
+        #   class Membership < Familia::Horreum
+        #     feature :object_identifier
+        #     field :customer_objid
+        #     field :domain_objid
+        #     field :role
+        #     field :updated_at
+        #   end
+        #
+        #   class Domain < Familia::Horreum
+        #     participates_in Customer, :domains, through: :Membership
+        #   end
+        #
+        #   # Through model auto-created with deterministic key
+        #   customer.add_domains_instance(domain, through_attrs: { role: 'admin' })
+        #   # => #<Membership objid="customer:123:domain:456:membership">
+        #
+        module ThroughModelOperations
+          module_function
+
+          # Build a deterministic key for the through model
+          #
+          # The key format ensures uniqueness and allows direct lookup:
+          # {target.prefix}:{target.objid}:{participant.prefix}:{participant.objid}:{through.prefix}
+          #
+          # @param target [Object] The target instance (e.g., customer)
+          # @param participant [Object] The participant instance (e.g., domain)
+          # @param through_class [Class] The through model class
+          # @return [String] Deterministic key for the through model
+          #
+          def build_key(target:, participant:, through_class:)
+            "#{target.class.config_name}:#{target.objid}:" \
+            "#{participant.class.config_name}:#{participant.objid}:" \
+            "#{through_class.config_name}"
+          end
+
+          # Find or create a through model instance
+          #
+          # This method is idempotent - calling it multiple times with the same
+          # target/participant pair will update the existing through model rather
+          # than creating duplicates.
+          #
+          # The through model's updated_at is set on both create and update for
+          # cache invalidation.
+          #
+          # @param through_class [Class] The through model class
+          # @param target [Object] The target instance
+          # @param participant [Object] The participant instance
+          # @param attrs [Hash] Additional attributes to set on through model
+          # @return [Object] The created or updated through model instance
+          #
+          def find_or_create(through_class:, target:, participant:, attrs: {})
+            key = build_key(target: target, participant: participant, through_class: through_class)
+
+            # Try to load existing model - load returns nil if key doesn't exist
+            existing = through_class.load(key)
+
+            # Check if we got a valid loaded object using the public API
+            # This is called outside transaction boundaries (see participant_methods.rb
+            # and target_methods.rb for the transaction boundary documentation)
+            if existing&.exists?
+              # Update existing through model with validated attributes
+              safe_attrs = validated_attrs(through_class, attrs)
+              safe_attrs.each { |k, v| existing.send("#{k}=", v) }
+              existing.updated_at = Familia.now.to_f if existing.respond_to?(:updated_at=)
+              # Save returns boolean, but we want to return the model instance
+              existing.save if safe_attrs.any? || existing.respond_to?(:updated_at=)
+              existing  # Return the model, not the save result
+            else
+              # Create new through model with our deterministic key as objid
+              # Pass objid during initialization to prevent auto-generation
+              inst = through_class.new(objid: key)
+
+              # Set foreign key fields if they exist (validated via respond_to?)
+              target_field = "#{target.class.config_name}_objid"
+              participant_field = "#{participant.class.config_name}_objid"
+              inst.send("#{target_field}=", target.objid) if inst.respond_to?("#{target_field}=")
+              inst.send("#{participant_field}=", participant.objid) if inst.respond_to?("#{participant_field}=")
+
+              # Set updated_at for cache invalidation
+              inst.updated_at = Familia.now.to_f if inst.respond_to?(:updated_at=)
+
+              # Set custom attributes (validated against field schema)
+              safe_attrs = validated_attrs(through_class, attrs)
+              safe_attrs.each { |k, v| inst.send("#{k}=", v) }
+
+              # Save returns boolean, but we want to return the model instance
+              inst.save
+              inst  # Return the model, not the save result
+            end
+          end
+
+          # Find and destroy a through model instance
+          #
+          # Used during remove operations to clean up the join table entry.
+          #
+          # @param through_class [Class] The through model class
+          # @param target [Object] The target instance
+          # @param participant [Object] The participant instance
+          # @return [void]
+          #
+          def find_and_destroy(through_class:, target:, participant:)
+            key = build_key(target: target, participant: participant, through_class: through_class)
+            existing = through_class.load(key)
+            # Use the public exists? method for a more robust check
+            existing&.destroy! if existing&.exists?
+          end
+
+          # Validate attribute keys against the through model's field schema
+          #
+          # This prevents arbitrary method invocation by ensuring only defined
+          # fields can be set via the attrs hash.
+          #
+          # @param through_class [Class] The through model class
+          # @param attrs [Hash] Attributes to validate
+          # @return [Hash] Only attributes whose keys match defined fields
+          #
+          def validated_attrs(through_class, attrs)
+            return {} if attrs.nil? || attrs.empty?
+
+            valid_fields = through_class.fields.map(&:to_sym)
+            attrs.select { |k, _v| valid_fields.include?(k.to_sym) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -7,6 +7,7 @@ require_relative 'participation_membership'
 require_relative 'collection_operations'
 require_relative 'participation/participant_methods'
 require_relative 'participation/target_methods'
+require_relative 'participation/through_model_operations'
 
 module Familia
   module Features
@@ -117,7 +118,7 @@ module Familia
           # - +ClassName.add_to_collection_name(instance)+ - Add instance to collection
           # - +ClassName.remove_from_collection_name(instance)+ - Remove instance from collection
           #
-          # ==== On Instances (Participant Methods, if bidirectional)
+          # ==== On Instances (Participant Methods, if generate_participant_methods)
           # - +instance.in_class_collection_name?+ - Check membership in class collection
           # - +instance.add_to_class_collection_name+ - Add self to class collection
           # - +instance.remove_from_class_collection_name+ - Remove self from class collection
@@ -134,7 +135,9 @@ module Familia
           #   - +:sorted_set+: Ordered by score (default)
           #   - +:set+: Unordered unique membership
           #   - +:list+: Ordered sequence allowing duplicates
-          # @param bidirectional [Boolean] Whether to generate convenience methods on instances (default: +true+)
+          # @param generate_participant_methods [Boolean] Whether to generate convenience methods on instances (default: +true+)
+          # @param through [Class, Symbol, String, nil] Optional join model class for
+          #        storing additional attributes. See +participates_in+ for details.
           #
           # @example Simple priority-based global collection
           #   class User < Familia::Horreum
@@ -160,7 +163,7 @@ module Familia
           # @see #participates_in for instance-level participation relationships
           # @since 1.0.0
           def class_participates_in(collection_name, score: nil,
-                                    type: :sorted_set, bidirectional: true)
+                                    type: :sorted_set, generate_participant_methods: true, through: nil)
             # Store metadata for this participation relationship
             participation_relationships << ParticipationRelationship.new(
               _original_target: self,   # For class-level, original and resolved are the same
@@ -168,21 +171,23 @@ module Familia
               collection_name: collection_name,
               score: score,
               type: type,
-              bidirectional: bidirectional,
+              generate_participant_methods: generate_participant_methods,
+              through: through,
+              method_prefix: nil,       # Not applicable for class-level participation
             )
 
             # STEP 1: Add collection management methods to the class itself
             # e.g., User.all_users, User.add_to_all_users(user)
             TargetMethods::Builder.build_class_level(self, collection_name, type)
 
-            # STEP 2: Add participation methods to instances (if bidirectional)
+            # STEP 2: Add participation methods to instances (if generate_participant_methods)
             # e.g., user.in_class_all_users?, user.add_to_class_all_users
-            return unless bidirectional
+            return unless generate_participant_methods
 
             # 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)
+            ParticipantMethods::Builder.build(self, 'class', collection_name, type, nil, through, nil)
           end
 
           # Define an instance-level participation relationship between two classes.
@@ -203,7 +208,7 @@ module Familia
           # - +target.remove_participant_class_name(participant)+ - Remove participant from collection
           # - +target.add_participant_class_names([participants])+ - Bulk add multiple participants
           #
-          # ==== On Participant Class (if bidirectional)
+          # ==== On Participant Class (if generate_participant_methods)
           # - +participant.in_target_collection_name?(target)+ - Check membership in target's collection
           # - +participant.add_to_target_collection_name(target)+ - Add self to target's collection
           # - +participant.remove_from_target_collection_name(target)+ - Remove self from target's collection
@@ -233,12 +238,18 @@ module Familia
           #        different scores (default)
           #   - +:set+: Unordered unique membership
           #   - +:list+: Ordered sequence, allows duplicates
-          # @param bidirectional [Boolean] Whether to generate reverse collection
+          # @param generate_participant_methods [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.
+          # @param through [Class, Symbol, String, nil] Optional join model class for
+          #        storing additional attributes on the relationship. The through model:
+          #   - Must use +feature :object_identifier+
+          #   - Gets auto-created when adding to collection (via +through_attrs:+ param)
+          #   - Gets auto-destroyed when removing from collection
+          #   - Uses deterministic keys: +{target}:{id}:{participant}:{id}:{through}+
           #
           # @example Basic domain-employee relationship
           #
@@ -284,7 +295,7 @@ module Familia
           # @see ModelInstanceMethods#current_participations for membership queries
           # @see ModelInstanceMethods#calculate_participation_score for scoring details
           #
-          def participates_in(target, collection_name, score: nil, type: :sorted_set, bidirectional: true, as: nil)
+          def participates_in(target, collection_name, score: nil, type: :sorted_set, generate_participant_methods: true, as: nil, through: nil, method_prefix: nil)
 
             # Normalize the target class parameter
             target_class = Familia.resolve_class(target)
@@ -306,6 +317,17 @@ module Familia
               ERROR
             end
 
+            # Validate through class if provided
+            if through
+              through_class = Familia.resolve_class(through)
+              raise ArgumentError, "Cannot resolve through class: #{through.inspect}" unless through_class
+
+              unless through_class.respond_to?(:features_enabled) &&
+                     through_class.features_enabled.include?(:object_identifier)
+                raise ArgumentError, "Through model #{through_class} must use `feature :object_identifier`"
+              end
+            end
+
             # Store metadata for this participation relationship
             participation_relationships << ParticipationRelationship.new(
               _original_target: target,      # Original value as passed (Symbol/String/Class)
@@ -313,7 +335,9 @@ module Familia
               collection_name: collection_name,
               score: score,
               type: type,
-              bidirectional: bidirectional,
+              generate_participant_methods: generate_participant_methods,
+              through: through,
+              method_prefix: method_prefix,
             )
 
             # STEP 0: Add participations tracking field to PARTICIPANT class (Domain)
@@ -322,14 +346,14 @@ module Familia
 
             # 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)
+            TargetMethods::Builder.build(target_class, collection_name, type, through)
 
             # STEP 2: Add participation methods to PARTICIPANT class (Domain) - only if
-            # bidirectional. e.g. in_employee_domains?, add_to_employee_domains, etc.
-            if bidirectional
+            # generate_participant_methods. e.g. in_employee_domains?, add_to_employee_domains, etc.
+            if generate_participant_methods
               # `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)
+              ParticipantMethods::Builder.build(self, target_class, collection_name, type, as, through, method_prefix)
             end
           end
 

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

@@ -21,7 +21,9 @@ module Familia
         :collection_name,     # Symbol name of the collection (e.g., :members, :domains)
         :score,               # Proc/Symbol/nil - score calculator for sorted sets
         :type,                # Symbol - collection type (:sorted_set, :set, :list)
-        :bidirectional,       # Boolean/Symbol - whether to generate reverse methods
+        :generate_participant_methods,  # Boolean - whether to generate participant methods
+        :through,             # Symbol/Class/nil - through model class for join table pattern
+        :method_prefix,       # Symbol/nil - custom prefix for reverse method names (e.g., :team)
       ) do
         # Get a unique key for this participation relationship
         # Useful for comparisons and hash keys
@@ -53,6 +55,22 @@ module Familia
           target_class_base == comparison_target_base &&
             collection_name == comparison_collection.to_sym
         end
+
+        # Check if this relationship uses a through model
+        #
+        # @return [Boolean] true if through model is configured
+        def through_model?
+          !through.nil?
+        end
+
+        # Resolve the through class to an actual Class object
+        #
+        # @return [Class, nil] The resolved through class or nil
+        def resolved_through_class
+          return nil unless through
+
+          through.is_a?(Class) ? through : Familia.resolve_class(through)
+        end
       end
     end
   end

data/lib/familia/features/relationships.rb

@@ -38,7 +38,7 @@ module Familia
     #
     #     # Participation with bidirectional control (no method collisions)
     #     participates_in Customer, :domains
-    #     participates_in Team, :domains, bidirectional: false
+    #     participates_in Team, :domains, generate_participant_methods: false
     #     participates_in Organization, :domains, type: :set
     #   end
     #

data/lib/familia/version.rb

@@ -4,5 +4,5 @@
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.0.0.pre22'.freeze unless defined?(Familia::VERSION)
+  VERSION = '2.0.0.pre23'.freeze unless defined?(Familia::VERSION)
 end

data/pr_agent.toml

@@ -9,12 +9,17 @@ response_language = "en"
 # Enable RAG context enrichment for codebase duplication compliance checks
 enable_rag = true
 # Include related repositories for comprehensive context
-rag_repo_list = ['delano/familia', 'delano/tryouts', 'delano/otto']
+rag_repo_list = ['onetimesecret/onetimesecret', 'delano/tryouts']
 
 [compliance]
 # Reference custom compliance checklist for project-specific rules
 custom_compliance_path = "pr_compliance_checklist.yaml"
 
+[pr_reviewer]
+# Disable automatic label additions (triggers Claude review workflow noise)
+enable_review_labels_security = false
+enable_review_labels_effort = false
+
 [ignore]
 # Reduce noise by excluding generated files and build artifacts
 glob = [

data/try/features/relationships/participation_commands_verification_spec.rb

@@ -30,7 +30,7 @@ RSpec.describe 'participation_commands_verification_try' do
       field :display_domain
       field :created_at
       participates_in ReverseIndexCustomer, :domains, score: :created_at
-      participates_in ReverseIndexCustomer, :preferred_domains, bidirectional: true
+      participates_in ReverseIndexCustomer, :preferred_domains, generate_participant_methods: true
       class_participates_in :all_domains, score: :created_at
     end
   end

data/try/features/relationships/participation_commands_verification_try.rb

@@ -49,7 +49,7 @@ class ReverseIndexDomain < Familia::Horreum
   field :created_at
 
   participates_in ReverseIndexCustomer, :domains, score: :created_at
-  participates_in ReverseIndexCustomer, :preferred_domains, bidirectional: true
+  participates_in ReverseIndexCustomer, :preferred_domains, generate_participant_methods: true
   class_participates_in :all_domains, score: :created_at
 end
 

data/try/features/relationships/participation_method_prefix_try.rb

@@ -0,0 +1,133 @@
+# try/features/relationships/participation_method_prefix_try.rb
+#
+# frozen_string_literal: true
+
+require_relative '../../../lib/familia'
+
+# Test the method_prefix: option for participates_in
+# This allows shorter reverse method names for namespaced classes
+
+# Simulate a namespaced target class
+module ::Admin
+  class MethodPrefixTeam < Familia::Horreum
+    feature :relationships
+
+    identifier_field :team_id
+    field :team_id
+    field :name
+
+    sorted_set :members
+    sorted_set :admins
+
+    def init
+      @team_id ||= "team_#{SecureRandom.hex(4)}"
+    end
+  end
+end
+
+# Test class using method_prefix: option
+class ::MethodPrefixUser < Familia::Horreum
+  feature :relationships
+
+  identifier_field :user_id
+  field :user_id
+  field :email
+
+  # Use method_prefix to get shorter method names
+  # Instead of admin_method_prefix_team_instances, we get team_instances
+  participates_in Admin::MethodPrefixTeam, :members, method_prefix: :team
+
+  def init
+    @user_id ||= "user_#{SecureRandom.hex(4)}"
+  end
+end
+
+# Test class using as: which should take precedence over method_prefix:
+class ::MethodPrefixPriorityUser < Familia::Horreum
+  feature :relationships
+
+  identifier_field :user_id
+  field :user_id
+  field :email
+
+  # as: takes precedence over method_prefix:
+  participates_in Admin::MethodPrefixTeam, :admins, method_prefix: :team, as: :my_teams
+
+  def init
+    @user_id ||= "user_#{SecureRandom.hex(4)}"
+  end
+end
+
+# Test class without method_prefix (default behavior)
+class ::MethodPrefixDefaultUser < Familia::Horreum
+  feature :relationships
+
+  identifier_field :user_id
+  field :user_id
+  field :email
+
+  # Default: uses config_name (method_prefix_team - demodularized, no namespace)
+  participates_in Admin::MethodPrefixTeam, :members
+
+  def init
+    @user_id ||= "user_#{SecureRandom.hex(4)}"
+  end
+end
+
+@user = MethodPrefixUser.new(email: 'alice@example.com')
+@priority_user = MethodPrefixPriorityUser.new(email: 'bob@example.com')
+@default_user = MethodPrefixDefaultUser.new(email: 'charlie@example.com')
+@team = Admin::MethodPrefixTeam.new(name: 'Engineering')
+
+## method_prefix: generates shortened method names
+# The method_prefix: :team option should generate team_* methods
+@user.respond_to?(:team_instances)
+#=> true
+
+## method_prefix: generates team_ids method
+@user.respond_to?(:team_ids)
+#=> true
+
+## method_prefix: generates team? method
+@user.respond_to?(:team?)
+#=> true
+
+## method_prefix: generates team_count method
+@user.respond_to?(:team_count)
+#=> true
+
+## method_prefix: does NOT generate verbose config_name methods
+# The verbose admin_method_prefix_team_* methods should not be created
+@user.respond_to?(:admin_method_prefix_team_instances)
+#=> false
+
+## as: takes precedence over method_prefix:
+# When both as: and method_prefix: are provided, as: wins
+@priority_user.respond_to?(:my_teams_instances)
+#=> true
+
+## as: takes precedence - method_prefix method NOT generated
+@priority_user.respond_to?(:team_instances)
+#=> false
+
+## default behavior preserved when no method_prefix
+# Without method_prefix:, the config_name is used (method_prefix_team)
+# Note: config_name uses the class name without namespace
+@default_user.respond_to?(:method_prefix_team_instances)
+#=> true
+
+## default behavior - no custom shortened method names
+# The team_instances method is not generated unless method_prefix: :team is used
+@default_user.respond_to?(:team_instances)
+#=> false
+
+## ParticipationRelationship stores method_prefix
+# The relationship metadata should include the method_prefix
+rel = MethodPrefixUser.participation_relationships.first
+rel.method_prefix
+#=> :team
+
+## ParticipationRelationship method_prefix is nil for default
+rel_default = MethodPrefixDefaultUser.participation_relationships.first
+rel_default.method_prefix
+#=> nil

data/try/features/relationships/participation_reverse_index_try.rb

@@ -28,7 +28,7 @@ class ReverseIndexDomain < Familia::Horreum
   field :created_at
 
   participates_in ReverseIndexCustomer, :domains, score: :created_at
-  participates_in ReverseIndexCustomer, :preferred_domains, bidirectional: true
+  participates_in ReverseIndexCustomer, :preferred_domains, generate_participant_methods: true
   class_participates_in :all_domains, score: :created_at
 end
 

data/try/features/relationships/{participation_bidirectional_try.rb → participation_reverse_methods_try.rb}

@@ -1,10 +1,10 @@
-# try/features/relationships/participation_bidirectional_try.rb
+# try/features/relationships/participation_reverse_methods_try.rb
 #
 # frozen_string_literal: true
 
 require_relative '../../../lib/familia'
 
-# Test demonstrating true bidirectional participation functionality
+# Test demonstrating reverse collection methods (generate_participant_methods: true)
 # This shows the improvement from asymmetric to symmetric relationship access
 
 # Setup test classes
@@ -51,8 +51,8 @@ class ::ProjectUser < Familia::Horreum
   field :name
   field :role
 
-  # Define bidirectional participation relationships
-  # These will auto-generate reverse collection methods with _instances suffix
+  # Define participation relationships with reverse collection methods
+  # These auto-generate methods like user.project_team_instances (when generate_participant_methods: true)
   participates_in ProjectTeam, :members          # Generates: user.project_team_instances
   participates_in ProjectTeam, :admins           # Also adds to user.project_team_instances (union)
   participates_in ProjectOrganization, :employees # Generates: user.project_organization_instances
@@ -197,13 +197,13 @@ contracting_orgs_instances.map(&:name)
 @team1.admins.to_a
 #=> [@user1.identifier]
 
-## Test bidirectional consistency - forward direction
+## Test symmetric consistency - forward direction
 team1_member_ids = @team1.members.to_a
 team1_members = ProjectUser.load_multi(team1_member_ids).compact
 team1_members.map(&:name)
 #=> ["Alice"]
 
-## Test bidirectional consistency - reverse direction
+## Test symmetric consistency - reverse direction
 user1_teams = @user1.project_team_instances
 user1_team_ids = user1_teams.map(&:identifier)
 user1_team_ids.include?(@team1.identifier)