familia 2.0.0.pre21 → 2.0.0.pre23

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/horreum/database_commands.rb

@@ -263,15 +263,20 @@ module Familia
       #
       #   | Scenario | Use | Why |
       #   |----------|-----|-----|
-      #   | Check if exists, then create | WATCH | Must prevent duplicate creation |
+      #   | First-one-wins / idempotency | SET NX | Atomic claim, no read needed |
+      #   | Distributed lock acquisition | SET NX EX | Claim with automatic expiry |
       #   | Read value, update conditionally | WATCH | Decision depends on current state |
       #   | Compare-and-swap operations | WATCH | Need optimistic locking |
       #   | Version-based updates | WATCH | Must detect concurrent changes |
+      #   | Status transitions (pending→processing) | WATCH | Must verify current state |
       #   | Batch field updates | MULTI only | No conditional logic |
       #   | Increment + timestamp together | MULTI only | Concurrent increments OK |
       #   | Save object atomically | MULTI only | Just need atomicity |
       #   | Update indexes with save | MULTI only | No state checking needed |
       #
+      #    If you don't need to read before deciding, WATCH adds complexity
+      #    without benefit. SET NX handles the "claim" pattern in one atomic shot.
+      #
       # @param suffix_override [String, nil] Optional suffix override
       # @return [String] 'OK' on success
       def watch(...)

data/lib/familia/horreum/management.rb

@@ -383,7 +383,7 @@ module Familia
       #
       def destroy!(identifier, suffix = nil)
         suffix ||= self.suffix
-        return MultiResult.new(false, []) if identifier.to_s.empty?
+        raise Familia::NoIdentifier, "#{self} requires non-empty identifier" if identifier.to_s.empty?
 
         objkey = dbkey identifier, suffix
 
@@ -450,22 +450,153 @@ module Familia
       def all(suffix = nil)
         suffix ||= self.suffix
         # objects that could not be parsed will be nil
-        keys(suffix).filter_map { |k| find_by_key(k) }
+        find_keys(suffix).filter_map { |k| find_by_key(k) }
       end
 
-      def any?(filter = '*')
-        matching_keys_count(filter).positive?
+      # Returns the number of tracked instances (fast, from instances sorted set).
+      #
+      # This method provides O(1) performance by querying the `instances` sorted set,
+      # which is automatically maintained when objects are created/destroyed through
+      # Familia. However, objects deleted outside Familia (e.g., direct Redis commands)
+      # may leave stale entries.
+      #
+      # @return [Integer] Number of instances in the instances sorted set
+      #
+      # @example
+      #   User.create(email: 'test@example.com')
+      #   User.count  #=> 1
+      #
+      # @note For authoritative count, use {#scan_count} (production-safe) or {#keys_count} (blocking)
+      # @see #scan_count Production-safe authoritative count via SCAN
+      # @see #keys_count Blocking authoritative count via KEYS
+      # @see #instances The underlying sorted set
+      #
+      def count
+        instances.count
       end
+      alias size count
+      alias length count
 
-      # Returns the number of dbkeys matching the given filter pattern
-      # @param filter [String] dbkey pattern to match (default: '*')
-      # @return [Integer] Number of matching keys
+      # Returns authoritative count using blocking KEYS command (production-dangerous).
       #
-      def matching_keys_count(filter = '*')
+      # ⚠️ WARNING: This method uses the KEYS command which blocks Redis during execution.
+      # It scans ALL keys in the database and should NEVER be used in production.
+      #
+      # @param filter [String] Key pattern to match (default: '*')
+      # @return [Integer] Number of matching keys in Redis
+      #
+      # @example
+      #   User.keys_count       #=> 1  (all User objects)
+      #   User.keys_count('a*') #=> 1  (Users with IDs starting with 'a')
+      #
+      # @note For production-safe authoritative count, use {#scan_count}
+      # @see #scan_count Production-safe alternative using SCAN
+      # @see #count Fast count from instances sorted set
+      #
+      def keys_count(filter = '*')
         dbclient.keys(dbkey(filter)).compact.size
       end
-      alias size matching_keys_count
-      alias length matching_keys_count
+
+      # Returns authoritative count using non-blocking SCAN command (production-safe).
+      #
+      # This method uses cursor-based SCAN iteration to count matching keys without
+      # blocking Redis. Safe for production use as it processes keys in chunks.
+      #
+      # @param filter [String] Key pattern to match (default: '*')
+      # @return [Integer] Number of matching keys in Redis
+      #
+      # @example
+      #   User.scan_count       #=> 1  (all User objects)
+      #   User.scan_count('a*') #=> 1  (Users with IDs starting with 'a')
+      #
+      # @note For fast count (potentially stale), use {#count}
+      # @see #count Fast count from instances sorted set
+      # @see #keys_count Blocking alternative (production-dangerous)
+      #
+      def scan_count(filter = '*')
+        pattern = dbkey(filter)
+        count = 0
+        cursor = "0"
+
+        loop do
+          cursor, keys = dbclient.scan(cursor, match: pattern, count: 1000)
+          count += keys.size
+          break if cursor == "0"
+        end
+
+        count
+      end
+      alias count! scan_count
+
+      # Checks if any tracked instances exist (fast, from instances sorted set).
+      #
+      # This method provides O(1) performance by querying the `instances` sorted set.
+      # However, objects deleted outside Familia may leave stale entries.
+      #
+      # @return [Boolean] true if instances sorted set is non-empty
+      #
+      # @example
+      #   User.create(email: 'test@example.com')
+      #   User.any?  #=> true
+      #
+      # @note For authoritative check, use {#scan_any?} (production-safe) or {#keys_any?} (blocking)
+      # @see #scan_any? Production-safe authoritative check via SCAN
+      # @see #keys_any? Blocking authoritative check via KEYS
+      # @see #count Fast count of instances
+      #
+      def any?
+        count.positive?
+      end
+
+      # Checks if any objects exist using blocking KEYS command (production-dangerous).
+      #
+      # ⚠️ WARNING: This method uses the KEYS command which blocks Redis during execution.
+      # It scans ALL keys in the database and should NEVER be used in production.
+      #
+      # @param filter [String] Key pattern to match (default: '*')
+      # @return [Boolean] true if any matching keys exist in Redis
+      #
+      # @example
+      #   User.keys_any?       #=> true  (any User objects)
+      #   User.keys_any?('a*') #=> true  (Users with IDs starting with 'a')
+      #
+      # @note For production-safe authoritative check, use {#scan_any?}
+      # @see #scan_any? Production-safe alternative using SCAN
+      # @see #any? Fast existence check from instances sorted set
+      #
+      def keys_any?(filter = '*')
+        keys_count(filter).positive?
+      end
+
+      # Checks if any objects exist using non-blocking SCAN command (production-safe).
+      #
+      # This method uses cursor-based SCAN iteration to check for matching keys without
+      # blocking Redis. Safe for production use and returns early on first match.
+      #
+      # @param filter [String] Key pattern to match (default: '*')
+      # @return [Boolean] true if any matching keys exist in Redis
+      #
+      # @example
+      #   User.scan_any?       #=> true  (any User objects)
+      #   User.scan_any?('a*') #=> true  (Users with IDs starting with 'a')
+      #
+      # @note For fast check (potentially stale), use {#any?}
+      # @see #any? Fast existence check from instances sorted set
+      # @see #keys_any? Blocking alternative (production-dangerous)
+      #
+      def scan_any?(filter = '*')
+        pattern = dbkey(filter)
+        cursor = "0"
+
+        loop do
+          cursor, keys = dbclient.scan(cursor, match: pattern, count: 100)
+          return true unless keys.empty?
+          break if cursor == "0"
+        end
+
+        false
+      end
+      alias any! scan_any?
 
       # Instantiates an object from a hash of field values.
       #

data/lib/familia/horreum/persistence.rb

@@ -396,6 +396,9 @@ module Familia
               obj.delete!
             end
           end
+
+          # Remove from instances collection if available
+          self.class.instances.remove(identifier) if self.class.respond_to?(:instances)
         end
 
         # Structured lifecycle logging and instrumentation

data/lib/familia/identifier_extractor.rb

@@ -29,7 +29,7 @@ module Familia
     # @return [String] The extracted identifier or class name
     # @raise [Familia::NotDistinguishableError] If value is not a Class or Familia::Base
     #
-    def identifier_extractor(value, strict_values: true)
+    def identifier_extractor(value)
       case value
       when ::Symbol, ::String, ::Integer, ::Float
         Familia.trace :IDENTIFIER_EXTRACTOR, nil, 'simple_value' if Familia.debug?

data/lib/familia/version.rb

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

data/lib/multi_result.rb

@@ -2,25 +2,28 @@
 #
 # frozen_string_literal: true
 
-# Represents the result of a Valkey/Redis transaction operation.
+# Represents the result of a Valkey/Redis transaction or pipeline operation.
 #
-# This class encapsulates the outcome of a Database transaction,
-# providing access to both the success status and the individual
-# command results returned by the transaction.
+# This class encapsulates the outcome of a Database multi-command operation,
+# providing access to both the command results and derived success status
+# based on the presence of errors in the results.
 #
-# @attr_reader success [Boolean] Indicates whether all commands
-#   in the transaction completed successfully.
-# @attr_reader results [Array<String>] Array of return values
-#   from the Database commands executed in the transaction.
+# Success is determined by checking for Exception objects in the results array.
+# When Redis commands fail within a transaction or pipeline, they return
+# exception objects rather than raising them, allowing other commands to
+# continue executing.
+#
+# @attr_reader results [Array] Array of return values from the Database commands.
+#   Values can be strings, integers, booleans, or Exception objects for failed commands.
 #
 # @example Creating a MultiResult instance
-#   result = MultiResult.new(true, ["OK", "OK"])
+#   result = MultiResult.new(["OK", "OK", 1])
 #
 # @example Checking transaction success
 #   if result.successful?
-#     puts "Transaction completed successfully"
+#     puts "All commands completed without errors"
 #   else
-#     puts "Transaction failed"
+#     puts "#{result.errors.size} command(s) failed"
 #   end
 #
 # @example Accessing individual command results
@@ -28,24 +31,55 @@
 #     puts "Command #{index + 1} returned: #{value}"
 #   end
 #
+# @example Inspecting errors
+#   if result.errors?
+#     result.errors.each do |error|
+#       puts "Error: #{error.message}"
+#     end
+#   end
+#
 class MultiResult
-  # @return [Boolean] true if all commands in the transaction succeeded,
-  #   false otherwise
-  attr_reader :success
-
-  # @return [Array<String>] The raw return values from the Database commands
+  # @return [Array] The raw return values from the Database commands
   attr_reader :results
 
   # Creates a new MultiResult instance.
   #
-  # @param success [Boolean] Whether all commands succeeded
-  # @param results [Array<String>] The raw results from Database commands
-  def initialize(success, results)
-    @success = success
+  # @param results [Array] The raw results from Database commands.
+  #   Exception objects in the array indicate command failures.
+  def initialize(results)
     @results = results
   end
 
-  # Returns a tuple representing the result of the transaction.
+  # Returns all Exception objects from the results array.
+  #
+  # This method is memoized for performance when called multiple times
+  # on the same MultiResult instance.
+  #
+  # @return [Array<Exception>] Array of exceptions that occurred during execution
+  def errors
+    @errors ||= results.select { |ret| ret.is_a?(Exception) }
+  end
+
+  # Checks if any errors occurred during execution.
+  #
+  # @return [Boolean] true if at least one command failed, false otherwise
+  def errors?
+    !errors.empty?
+  end
+
+  # Checks if all commands completed successfully (no exceptions).
+  #
+  # This is the primary method for determining if a multi-command
+  # operation completed without errors.
+  #
+  # @return [Boolean] true if no exceptions in results, false otherwise
+  def successful?
+    errors.empty?
+  end
+  alias success? successful?
+  alias areyouhappynow? successful?
+
+  # Returns a tuple representing the result of the operation.
   #
   # @return [Array] A tuple containing the success status and the raw results.
   #   The success status is a boolean indicating if all commands succeeded.
@@ -61,21 +95,15 @@ class MultiResult
 
   # Returns the number of results in the multi-operation.
   #
-  # @return [Integer] The number of individual command results returned by the transaction.
+  # @return [Integer] The number of individual command results returned
   def size
     results.size
   end
 
+  # Returns a hash representation of the result.
+  #
+  # @return [Hash] Hash with :success and :results keys
   def to_h
     { success: successful?, results: results }
   end
-
-  # Convenient method to check if the commit was successful.
-  #
-  # @return [Boolean] true if all commands succeeded, false otherwise
-  def successful?
-    @success
-  end
-  alias success? successful?
-  alias areyouhappynow? successful?
 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 = [