familia 2.0.0.pre19 → 2.0.0.pre22

data/docs/guides/feature-relationships-participation.md

@@ -0,0 +1,263 @@
+# Relationships Participation Guide
+
+Participation creates bidirectional associations between Familia objects with automatic reverse tracking, semantic scoring, and lifecycle management.
+
+## Core Concepts
+
+Participation manages "belongs to" relationships where:
+- **Membership has meaning** - Customer owns Domains, User belongs to Teams
+- **Scores have semantic value** - Priority, timestamps, permissions
+- **Bidirectional tracking** - Both sides know about the relationship
+- **Lifecycle matters** - Automatic cleanup on destroy
+
+## Basic Usage
+
+```ruby
+class Domain < Familia::Horreum
+  feature :relationships
+  field :created_at
+
+  participates_in Customer, :domains, score: :created_at
+end
+
+class Customer < Familia::Horreum
+  feature :relationships
+  # sorted_set :domains created automatically
+end
+
+# Bidirectional relationship management
+customer.add_domains_instance(domain)     # Add with timestamp score
+domain.in_customer_domains?(customer)     # => true
+domain.customer_instances                 # => [customer]
+```
+
+## Collection Types
+
+### Sorted Set (Default)
+
+Ordered collections with semantic scores:
+
+```ruby
+participates_in Project, :tasks, score: :priority
+
+project.tasks.range(0, 4, order: 'DESC')  # Top 5 by priority
+task.score_in_project_tasks(project)      # Get current score
+```
+
+### Unsorted Set
+
+Simple membership without ordering:
+
+```ruby
+participates_in Team, :members, type: :set
+
+team.members.member?(user.identifier)     # Fast O(1) check
+```
+
+### List
+
+Ordered sequences:
+
+```ruby
+participates_in Playlist, :songs, type: :list
+
+song.position_in_playlist_songs(playlist)  # Get position
+```
+
+## Scoring Strategies
+
+### Field-Based
+
+```ruby
+participates_in Category, :articles, score: :published_at
+participates_in User, :bookmarks, score: :rating
+```
+
+### Lambda-Based
+
+```ruby
+participates_in Department, :employees, score: -> {
+  performance_rating * 100 + tenure_years * 10
+}
+```
+
+### Permission Encoding
+
+```ruby
+participates_in Customer, :domains, score: -> {
+  permission_encode(created_at, permission_bits)
+}
+
+customer.domains_with_permission(:read)  # Query by permission
+```
+
+## Class-Level Participation
+
+Track all instances automatically:
+
+```ruby
+class User < Familia::Horreum
+  class_participates_in :all_users, score: :created_at
+  class_participates_in :active_users,
+    score: ->(u) { u.active? ? u.last_activity : 0 }
+end
+
+User.all_users.size                # Total count
+User.active_users.range(0, 9)      # Top 10 active
+```
+
+## Multiple Collections
+
+Participants can belong to multiple collections:
+
+```ruby
+class User < Familia::Horreum
+  participates_in Team, :members
+  participates_in Team, :admins
+  participates_in Organization, :employees, as: :employers
+end
+
+# Separate methods per collection
+user.add_to_team_members(team)
+user.add_to_team_admins(team)
+
+# Reverse methods union collections
+user.team_instances      # Union of members + admins
+user.employers_instances  # Custom name via 'as:'
+```
+
+## Lifecycle Management
+
+### Automatic Tracking
+
+Familia maintains a reverse index for cleanup:
+
+```ruby
+domain.participations.members
+# => ["customer:cust_123:domains", "customer:cust_456:domains"]
+
+domain.current_participations
+# => [
+#   { collection_key: "customer:cust_123:domains", score: 1640995200 },
+#   { collection_key: "customer:cust_456:domains", score: 1640995300 }
+# ]
+```
+
+### Cleanup
+
+```ruby
+class Domain < Familia::Horreum
+  before_destroy :cleanup_relationships
+
+  def cleanup_relationships
+    # Automatic removal from all collections
+    super
+  end
+end
+```
+
+## Advanced Patterns
+
+### Conditional Scoring
+
+```ruby
+participates_in Project, :tasks, score: -> {
+  status == 'active' ? priority : 0
+}
+
+# Filter by score
+active_tasks = project.tasks.range_by_score(1, '+inf')
+```
+
+### Time-Based Expiration
+
+```ruby
+participates_in User, :sessions, score: :expires_at
+
+# Query active sessions
+now = Time.now.to_i
+active = user.sessions.range_by_score(now, '+inf')
+```
+
+### Validation
+
+```ruby
+def add_members_instance(user, score = nil)
+  raise "Team is full" if members.size >= max_members
+  raise "User not active" unless user.status == 'active'
+  super
+end
+```
+
+## Performance Best Practices
+
+### Bulk Operations
+
+```ruby
+# ✅ Efficient bulk add
+customer.add_domains([domain1, domain2, domain3])
+
+# ❌ Avoid loops
+domains.each { |d| customer.add_domains_instance(d) }
+```
+
+### Pagination
+
+```ruby
+# ✅ Paginated access
+customer.domains.range(0, 19)      # First 20
+customer.domains.range(20, 39)     # Next 20
+
+# ❌ Loading all
+customer.domains.to_a               # Loads all IDs
+```
+
+### Direct Collection Access
+
+```ruby
+# For IDs only
+customer.domains.to_a               # Just IDs
+customer.domains.merge([id1, id2])  # Bulk ID operations
+
+# For objects
+domain.customer_instances           # Efficient bulk loading
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Method not found:**
+- Ensure `feature :relationships` on both classes
+- Verify `participates_in` declaration
+- Check method naming patterns
+
+**Inconsistent relationships:**
+- Use transactions for complex operations
+- Implement validation in overridden methods
+- Monitor reverse index consistency
+
+**Performance issues:**
+- Use bulk operations
+- Implement pagination
+- Consider direct collection access for IDs
+
+### Debugging
+
+```ruby
+# Check configuration
+Domain.participation_relationships
+# => [{ target_class: Customer, collection_name: :domains, ... }]
+
+# Inspect participations
+domain.current_participations
+
+# Validate consistency
+domain.validate_relationships!
+```
+
+## See Also
+
+- [**Relationships Overview**](feature-relationships.md) - Core concepts
+- [**Methods Reference**](feature-relationships-methods.md) - Complete API
+- [**Indexing Guide**](feature-relationships-indexing.md) - Attribute lookups

data/docs/guides/feature-relationships.md

@@ -1,200 +1,182 @@
 # Relationships Feature Guide
 
-The Relationships feature transforms how you manage object associations in Familia applications. Instead of manually maintaining foreign keys and indexes, relationships provide automatic bidirectional links, efficient queries, and Ruby-like collection syntax that makes working with related objects feel natural and intuitive.
-
-This guide provides a breadth-first introduction to the four core relationship capabilities: **participation**, **indexing**, **querying**, and **cascading operations**.
+The Relationships feature provides automatic bidirectional associations between Familia objects, eliminating manual foreign key management while enabling efficient queries through Redis-native data structures.
 
 > [!TIP]
-> Enable relationships with `feature :relationships`, define associations with `participates_in`, and use clean Ruby syntax like `customer.domains << domain` to manage relationships.
-
-## What Are Relationships?
+> Enable with `feature :relationships` and define associations using `participates_in` for automatic method generation.
 
-Relationships automate object associations in Familia, eliminating manual foreign key management:
+## Quick Start
 
 ```ruby
-# Without relationships - manual and error-prone
-customer.domain_ids.add(domain.identifier)
-domain.customer_id = customer.identifier
-
-# With relationships - automatic and clean
-customer.domains << domain  # Updates both sides automatically
-```
-
-**Key Benefits:**
-- **Automatic bidirectional updates** - no manual synchronization
-- **Ruby-like syntax** - familiar `<<` and collection operations
-- **O(1) lookups** - efficient Valkey/Redis-backed indexing
-- **Lifecycle management** - automatic cleanup and maintenance
-
-## Core Relationship Capabilities
-
-### 1. Participation - Bidirectional Object Links
-
-Connect objects with automatic synchronization:
-
-```ruby
-class User < Familia::Horreum
+class Customer < Familia::Horreum
   feature :relationships
-  set :teams  # Collection holder
+  # Collection 'domains' created automatically
 end
 
-class Team < Familia::Horreum
+class Domain < Familia::Horreum
   feature :relationships
-  participates_in User, :teams  # Declares participation
+  participates_in Customer, :domains
 end
 
-# Usage - automatic bidirectional updates
-user.teams << team
-team.in_user_teams?(user)  # => true
+# Automatic bidirectional relationship management
+customer.add_domains_instance(domain)      # Add relationship
+domain.in_customer_domains?(customer)      # => true
+domain.customer_instances                  # => [customer]
 ```
 
-**Many-to-Many Example:**
+## Core Capabilities
+
+### Participation - Bidirectional Associations
+
+Create semantic relationships between objects with automatic reverse tracking:
+
 ```ruby
-class Project < Familia::Horreum
-  set :contributors, :reviewers
+class User < Familia::Horreum
+  feature :relationships
+  participates_in Team, :members, score: :joined_at
+  participates_in Team, :admins
 end
 
-class Developer < Familia::Horreum
-  participates_in Project, :contributors
-  participates_in Project, :reviewers
-end
+# Generated methods on Team (target)
+team.add_members_instance(user)           # Add single member
+team.add_members([user1, user2])          # Bulk add
+team.members.range(0, 9)                  # First 10 members
 
-project.contributors << alice  # Alice contributes
-project.reviewers << bob       # Bob reviews
+# Generated methods on User (participant)
+user.add_to_team_members(team)            # Add self to team
+user.in_team_admins?(team)                # Check membership
+user.team_instances                       # All teams (members + admins)
 ```
 
-### 2. Indexing - Automatic Object Tracking
+### Indexing - Fast Attribute Lookups
 
-Enable O(1) lookups with automatic index management:
+Enable O(1) field-based queries with automatic index management:
 
 ```ruby
 class User < Familia::Horreum
   feature :relationships
-  field :email, :created_at
-
-  # Global unique lookups
-  class_indexed_by :email, :email_lookup
+  field :email, :username
 
-  # Scored tracking collections
-  class_participates_in :all_users, score: :created_at
+  # Global unique indexes (auto-managed on save/destroy)
+  unique_index :email, :email_lookup
+  unique_index :username, :username_lookup
 end
 
-# Automatic on save/destroy
-User.find_by_email("alice@example.com")    # O(1) lookup
-User.all_users.range(0, 9)                 # Most recent 10 users
-```
+User.find_by_email("alice@example.com")   # O(1) lookup
+User.find_by_username("alice")            # O(1) lookup
 
-**Relationship-Scoped Indexing:**
-```ruby
-class Domain < Familia::Horreum
-  participates_in Customer, :domains
-  indexed_by :name, :domain_index, target: Customer  # Unique per customer
+# Scoped indexing (manual management required)
+class Employee < Familia::Horreum
+  feature :relationships
+  unique_index :badge_number, :badge_index, within: Company
+  multi_index :department, :dept_index, within: Company
 end
 
-customer.find_by_name("example.com")  # Find domain within this customer
+employee.add_to_company_badge_index(company)
+company.find_by_badge_number("12345")     # Scoped lookup
+company.find_all_by_department("engineering")  # Multi-value
 ```
 
-### 3. Querying - Ruby-like Collection Operations
+### Scoring - Semantic Ordering
 
-Work with relationships like standard Ruby collections:
+Use scores for temporal tracking, priority systems, or custom ordering:
 
 ```ruby
-# Standard collection operations
-org.members << alice                    # Add relationship
-org.members.merge([id1, id2, id3])     # Bulk additions
-org.members.size                       # Count relationships
-org.members.empty?                     # Check if any exist
-
-# Set operations
-common = org1.members & org2.members   # Intersection
-all = org1.members | org2.members      # Union
-
-# Load actual objects when needed
-member_ids = org.members.to_a
-members = Person.multiget(*member_ids)  # Efficient bulk loading
+class Task < Familia::Horreum
+  feature :relationships
+  field :priority, :created_at
+
+  # Field-based scoring
+  participates_in Project, :tasks, score: :priority
+
+  # Lambda-based scoring
+  participates_in Sprint, :tasks, score: -> {
+    priority * 100 + (Time.now - created_at) / 3600
+  }
+end
+
+project.tasks.range(0, 4, order: 'DESC')  # Top 5 by priority
+sprint.tasks.range_by_score(500, '+inf')  # High priority tasks
 ```
 
-> [!WARNING]
-> Collections store identifiers, not objects. Use `multiget` for efficient bulk loading.
+## Generated Method Reference
+
+### When Domain declares `participates_in Customer, :domains`
+
+| Class | Method | Purpose |
+|-------|--------|---------|
+| **Customer** | `domains` | Access collection |
+| | `add_domains_instance(domain)` | Add single item |
+| | `add_domains([domains])` | Bulk add |
+| | `remove_domains_instance(domain)` | Remove item |
+| **Domain** | `add_to_customer_domains(customer)` | Add to collection |
+| | `remove_from_customer_domains(customer)` | Remove from collection |
+| | `in_customer_domains?(customer)` | Check membership |
+| | `score_in_customer_domains(customer)` | Get score (sorted_set) |
+| | `customer_instances` | Load all customers |
+| | `customer_ids` | Get customer IDs |
+| | `customer?` | Has any customers? |
+| | `customer_count` | Count relationships |
 
-### 4. Cascading Operations - Scored Relationships
+## Common Patterns
 
-Use scores for time-based tracking and priority systems:
+### Multiple Collections
 
 ```ruby
-class Timeline < Familia::Horreum
-  feature :relationships
-  sorted_set :events  # Scored collection
-end
-
-class Event < Familia::Horreum
+class User < Familia::Horreum
   feature :relationships
-  field :timestamp, :priority
-  participates_in Timeline, :events, score: :timestamp
+  participates_in Project, :contributors
+  participates_in Project, :reviewers
+  participates_in Organization, :employees, as: :employers
 end
 
-# Automatic scoring when relationships established
-timeline.events << event  # Uses event.timestamp as score
+# Separate methods per collection
+user.add_to_project_contributors(project)
+user.add_to_project_reviewers(project)
 
-# Time-based and priority queries
-recent = timeline.events.range_by_score((Time.now - 1.hour).to_i, '+inf')
-top_priority = project.tasks.range(0, 4, order: 'DESC')  # Highest priority first
+# Custom reverse method names
+user.employers_instances  # Instead of organization_instances
 ```
 
-**Common Scoring Patterns:**
-- **Timestamps** for chronological ordering
-- **Priority levels** for ranking systems
-- **User ratings** for recommendation systems
-- **Custom lambdas** for complex scoring logic
+### Class-Level Tracking
 
-## Best Practices
-
-**Performance:**
-- Use `merge([id1, id2, id3])` for bulk additions
-- Use `multiget(*ids)` for efficient bulk loading
-- Use pagination: `collection.range(0, 9)` instead of loading all
-
-**Lifecycle Management:**
 ```ruby
-def destroy
-  cleanup_relationships  # Remove from all relationships first
-  super
+class Customer < Familia::Horreum
+  feature :relationships
+  class_participates_in :all_customers, score: :created_at
+  class_participates_in :premium_customers,
+    score: ->(c) { c.tier == 'premium' ? c.last_activity : 0 }
 end
-```
 
-**Validation:**
-```ruby
-def add_member(user_id)
-  raise "Team is full" if members.size >= max_members
-  members << user_id
-end
+Customer.all_customers.size               # Total count
+Customer.premium_customers.range(0, 9)    # Top 10 premium
 ```
 
-## Common Patterns
+### Performance Optimization
 
-**Conditional Scoring:**
 ```ruby
-class_participates_in :active_users,
-  score: ->(user) { user.active? ? user.last_activity : 0 }
-```
+# Bulk operations
+team.add_members([user1, user2, user3])
 
-**Bidirectional Updates:**
-```ruby
-# ✅ Automatic bidirectional
-customer.domains << domain
+# Pagination
+team.members.range(0, 19)                 # First 20
+team.members.range(20, 39)                # Next 20
 
-# ❌ Manual (avoid)
-customer.domains.add(domain.identifier)
+# Direct ID access (no object loading)
+team.members.to_a                         # Just IDs
+team.member_instances                     # Load objects
 ```
 
----
+## Best Practices
 
-## See Also
+1. **Use bulk methods** for multiple additions: `add_domains([d1, d2, d3])`
+2. **Paginate large collections**: `range(0, 19)` instead of loading all
+3. **Leverage reverse methods**: `domain.customer_instances` for efficient loading
+4. **Clean up on destroy**: Call `cleanup_relationships` before deletion
+5. **Validate before adding**: Check capacity/eligibility in overridden methods
 
-- **[Technical Reference](../reference/api-technical.md#relationships-feature-v200-pre7)** - Implementation details and advanced patterns
-- **[Relationship Methods Guide](feature-relationships-methods.md)** - Complete method reference
-- **[Feature System Guide](feature-system.md)** - Understanding Familia's feature architecture
-- **[Implementation Guide](implementation.md)** - Production deployment and configuration patterns
+## See Also
 
-> [!NOTE]
-> **Next Steps:** Once you're comfortable with basic relationships, explore the [Relationship Methods Guide](feature-relationships-methods.md) for detailed method references, or check the [Technical Reference](../reference/api-technical.md#relationships-feature-v200-pre7) for advanced patterns like permission encoding and performance optimization.
+- [**Relationship Methods**](feature-relationships-methods.md) - Complete API reference
+- [**Participation Guide**](feature-relationships-participation.md) - Deep dive into associations
+- [**Indexing Guide**](feature-relationships-indexing.md) - Attribute lookup patterns