familia 2.0.0.pre8 → 2.0.0.pre12

data/docs/migrating/v2.0.0-pre7.md

@@ -0,0 +1,222 @@
+# Migrating Guide: Relationships System (v2.0.0-pre7)
+
+This guide covers adopting the comprehensive relationships system introduced in v2.0.0-pre7.
+
+## Relationships System Overview
+
+The v2.0.0-pre7 release introduces three powerful relationship types:
+
+- **`tracked_in`** - Multi-presence tracking with score encoding
+- **`indexed_by`** - O(1) hash-based lookups
+- **`member_of`** - Bidirectional membership with collision-free naming
+
+## Migration Steps
+
+### 1. Enable Relationships Feature
+
+Add the relationships feature to your models:
+
+```ruby
+class Customer < Familia::Horreum
+  feature :relationships  # Required for all relationship types
+
+  identifier_field :custid
+  field :custid, :name, :email
+end
+```
+
+### 2. Choose Appropriate Relationship Types
+
+**For Tracking Collections (sorted sets):**
+```ruby
+class Customer < Familia::Horreum
+  feature :relationships
+
+  # Global tracking with score-based sorting
+  tracked_in :all_customers, type: :sorted_set, score: :created_at
+
+  # Scoped tracking
+  tracked_in :active_users, type: :sorted_set, score: :last_seen
+end
+```
+
+**For Fast Lookups (hash indexes):**
+```ruby
+class Customer < Familia::Horreum
+  feature :relationships
+
+  # Global email index for O(1) lookups
+  indexed_by :email, :email_lookup, context: :global
+
+  # Domain-specific indexes
+  indexed_by :account_id, :account_lookup, context: Domain
+end
+```
+
+**For Bidirectional Membership:**
+```ruby
+class Domain < Familia::Horreum
+  feature :relationships
+
+  # Belongs to customer's domains collection
+  member_of Customer, :domains, type: :set
+end
+```
+
+### 3. Implement Permission Systems
+
+For access-controlled relationships:
+
+```ruby
+class Document < Familia::Horreum
+  feature :relationships
+  include Familia::Features::Relationships::PermissionManagement
+
+  # Permission-aware tracking
+  tracked_in Customer, :documents, score: :created_at
+
+  permission_tracking :user_permissions
+
+  def permission_bits
+    # Define permission levels (bit-encoded)
+    @permission_bits || 1  # Default: read-only
+  end
+end
+```
+
+### 4. Update Queries
+
+**Before (manual Redis operations):**
+```ruby
+# Manual sorted set operations
+redis.zadd("all_customers", customer.created_at, customer.custid)
+customers = redis.zrange("all_customers", 0, -1)
+```
+
+**After (relationship methods):**
+```ruby
+# Automatic method generation
+Customer.add_to_all_customers(customer)
+customers = Customer.all_customers.to_a
+```
+
+## Relationship Method Patterns
+
+### `tracked_in` Methods
+```ruby
+# Class methods generated:
+Customer.add_to_all_customers(customer)
+Customer.remove_from_all_customers(customer)
+Customer.all_customers  # Access sorted set directly
+```
+
+### `indexed_by` Methods
+```ruby
+# Class methods generated:
+Customer.add_to_email_lookup(customer)
+Customer.remove_from_email_lookup(customer)
+Customer.email_lookup.get(email)  # O(1) lookup
+```
+
+### `member_of` Methods
+```ruby
+# Instance methods generated:
+domain.add_to_customer_domains(customer)
+domain.remove_from_customer_domains(customer)
+domain.in_customer_domains?(customer)
+```
+
+## Permission System Migration
+
+### Basic Permission Encoding
+```ruby
+# Permission levels (bit-encoded)
+READ    = 1   # 001
+WRITE   = 4   # 100
+DELETE  = 32  # 100000
+ADMIN   = 128 # 10000000
+
+# Combine permissions
+user_permissions = READ | WRITE  # Can read and write
+admin_permissions = ADMIN        # All permissions via hierarchy
+```
+
+### Time-Based Permission Scores
+```ruby
+# Encode timestamp with permission bits
+timestamp = Time.now.to_i
+permissions = READ | WRITE
+score = Familia::Features::Relationships::ScoreEncoding.encode_score(timestamp, permissions)
+
+# Query by permission level
+documents_with_write_access = customer.documents.accessible_items(
+  permissions: WRITE,
+  collection_key: customer.documents.key
+)
+```
+
+## Performance Considerations
+
+### Relationship Type Selection
+
+**Use `indexed_by` for:**
+- Unique field lookups (email, username, ID)
+- Fields that need O(1) access
+- Reference relationships
+
+**Use `tracked_in` for:**
+- Time-ordered collections
+- Scored/ranked relationships
+- Permission-based access control
+
+**Use `member_of` for:**
+- Simple membership tracking
+- Bidirectional relationships
+- Set-based collections
+
+### Optimization Tips
+
+**Batch Operations:**
+```ruby
+# Instead of multiple individual operations
+customers.each { |c| Customer.add_to_all_customers(c) }
+
+# Use batch operations where available
+Customer.all_customers.add_batch(customers.map(&:identifier),
+                                 customers.map(&:created_at))
+```
+
+**Permission Queries:**
+```ruby
+# Efficient permission filtering
+accessible_docs = document.accessible_items(
+  collection_key: customer.documents.key,
+  minimum_permissions: READ
+)
+```
+
+## Breaking Changes
+
+### Method Name Changes
+- Relationship methods follow new naming patterns
+- Previous manual Redis operations need updating
+- Collection access methods standardized
+
+### Permission System
+- New bit-encoded permission system
+- Time-based scoring for temporal access
+- Permission hierarchy implementation required
+
+## Next Steps
+
+1. **Analyze Existing Relationships:** Review current Redis operations for optimization opportunities
+2. **Choose Relationship Types:** Select appropriate types based on usage patterns
+3. **Implement Permissions:** Add access control where needed
+4. **Update Queries:** Replace manual operations with generated relationship methods
+5. **Test Performance:** Benchmark relationship operations under load
+
+## Resources
+
+- [Relationships Methods Guide](../guides/relationships-methods.md) - Complete method reference
+- [Relationships Guide](../guides/Relationships-Guide.md) - Implementation examples
+- [Performance Guide](../guides/Implementation-Guide.md) - Optimization strategies

data/docs/overview.md

@@ -118,17 +118,16 @@ This is ideal for temporary data like authentication tokens or cache entries.
 
 ### Safe Dumping for APIs
 
-Control which fields are exposed when serializing objects:
+Control which fields are exposed when serializing objects using the clean DSL:
 
 ```ruby
 class User < Familia::Horreum
   feature :safe_dump
 
-  @safe_dump_fields = [
-    :id,
-    :email,
-    {full_name: ->(user) { "#{user.first_name} #{user.last_name}" }}
-  ]
+  # Use clean DSL methods instead of @safe_dump_fields
+  safe_dump_field :id
+  safe_dump_field :email
+  safe_dump_field :full_name, ->(user) { "#{user.first_name} #{user.last_name}" }
 
   field :id, :email, :first_name, :last_name, :password_hash
 end
@@ -137,7 +136,7 @@ user.safe_dump
 #=> {id: "123", email: "alice@example.com", full_name: "Alice Smith"}
 ```
 
-Prevents accidental exposure of sensitive data in API responses.
+The new DSL prevents accidental exposure of sensitive data and makes field definitions easier to organize in feature modules.
 
 ### Time-based Quantization
 

data/{examples/redis_command_validation_example.rb → docs/reference/auditing_database_commands.rb}

@@ -50,21 +50,21 @@ class TransferService
   end
 end
 
-puts "🧪 Redis Command Validation Framework Demo"
-puts "=" * 50
+puts '🧪 Redis Command Validation Framework Demo'
+puts '=' * 50
 
 # Clean up any existing test data
-cleanup_keys = Familia.dbclient.keys("account:*")
+cleanup_keys = Familia.dbclient.keys('account:*')
 Familia.dbclient.del(*cleanup_keys) if cleanup_keys.any?
 
 # Example 1: Basic Command Recording
 puts "\n1. Basic Command Recording"
-puts "-" * 30
+puts '-' * 30
 
 CommandRecorder = Familia::Validation::CommandRecorder
 CommandRecorder.start_recording
 
-account = Account.new(account_id: "acc001", balance: "1000", status: "active")
+account = Account.new(account_id: 'acc001', balance: '1000', status: 'active')
 account.save
 
 commands = CommandRecorder.stop_recording
@@ -73,12 +73,12 @@ commands.commands.each { |cmd| puts "  #{cmd}" }
 
 # Example 2: Transaction Detection
 puts "\n2. Transaction Detection"
-puts "-" * 30
+puts '-' * 30
 
 CommandRecorder.start_recording
 
-acc1 = Account.new(account_id: "acc002", balance: "2000")
-acc2 = Account.new(account_id: "acc003", balance: "500")
+acc1 = Account.new(account_id: 'acc002', balance: '2000')
+acc2 = Account.new(account_id: 'acc003', balance: '500')
 acc1.save
 acc2.save
 
@@ -96,7 +96,7 @@ end
 
 # Example 3: Validation with Expectations DSL
 puts "\n3. Command Validation with Expectations"
-puts "-" * 30
+puts '-' * 30
 
 begin
   validator = Familia::Validation::Validator.new
@@ -104,15 +104,15 @@ begin
   # This should pass - we expect the exact Redis commands
   result = validator.validate do |expect|
     expect.transaction do |tx|
-      tx.hset("account:acc004:object", "balance", "1500")
-        .hset("account:acc005:object", "balance", "1000")
-        .hset("account:acc004:object", "last_updated", Familia::Validation::ArgumentMatcher.new(:any_string))
-        .hset("account:acc005:object", "last_updated", Familia::Validation::ArgumentMatcher.new(:any_string))
+      tx.hset('account:acc004:object', 'balance', '1500')
+        .hset('account:acc005:object', 'balance', '1000')
+        .hset('account:acc004:object', 'last_updated', Familia::Validation::ArgumentMatcher.new(:any_string))
+        .hset('account:acc005:object', 'last_updated', Familia::Validation::ArgumentMatcher.new(:any_string))
     end
 
     # Execute the operation
-    acc4 = Account.new(account_id: "acc004", balance: "2000")
-    acc5 = Account.new(account_id: "acc005", balance: "500")
+    acc4 = Account.new(account_id: 'acc004', balance: '2000')
+    acc5 = Account.new(account_id: 'acc005', balance: '500')
     acc4.save
     acc5.save
 
@@ -121,51 +121,49 @@ begin
 
   puts "Validation result: #{result.valid? ? 'PASS ✅' : 'FAIL ❌'}"
   puts "Summary: #{result.summary}"
-
-rescue => e
+rescue StandardError => e
   puts "Validation demo encountered error: #{e.message}"
-  puts "This is expected as the framework needs Redis middleware integration"
+  puts 'This is expected as the framework needs Redis middleware integration'
 end
 
 # Example 4: Performance Analysis
 puts "\n4. Performance Analysis"
-puts "-" * 30
+puts '-' * 30
 
 begin
   commands = Familia::Validation.capture_commands do
     # Create multiple accounts
     accounts = []
     (1..5).each do |i|
-      account = Account.new(account_id: "perf#{i}", balance: "1000")
+      account = Account.new(account_id: "perf#{i}", balance: '1000')
       account.save
       accounts << account
     end
 
     # Perform operations
-    accounts[0].balance = "1100"
+    accounts[0].balance = '1100'
     accounts[0].save
   end
 
   analyzer = Familia::Validation::PerformanceAnalyzer.new(commands)
   analysis = analyzer.analyze
 
-  puts "Performance Analysis:"
+  puts 'Performance Analysis:'
   puts "  Total Commands: #{analysis[:total_commands]}"
   puts "  Command Types: #{analysis[:command_type_breakdown].keys.join(', ')}"
   puts "  Efficiency Score: #{analysis[:efficiency_score]}/100"
-
-rescue => e
+rescue StandardError => e
   puts "Performance analysis encountered error: #{e.message}"
 end
 
 # Example 5: Atomicity Validation
 puts "\n5. Atomicity Validation"
-puts "-" * 30
+puts '-' * 30
 
 begin
   # Test atomic vs non-atomic operations
-  acc6 = Account.new(account_id: "acc006", balance: "3000")
-  acc7 = Account.new(account_id: "acc007", balance: "1000")
+  acc6 = Account.new(account_id: 'acc006', balance: '3000')
+  acc7 = Account.new(account_id: 'acc007', balance: '1000')
   acc6.save
   acc7.save
 
@@ -180,13 +178,12 @@ begin
   result = atomicity_validator.validate
 
   puts "Atomicity validation: #{result.valid? ? 'PASS ✅' : 'FAIL ❌'}"
-
-rescue => e
+rescue StandardError => e
   puts "Atomicity validation encountered error: #{e.message}"
 end
 
 puts "\n6. Framework Architecture Overview"
-puts "-" * 30
+puts '-' * 30
 puts "
 The Redis Command Validation Framework provides:
 
@@ -224,8 +221,8 @@ Key Benefits:
 "
 
 # Cleanup
-cleanup_keys = Familia.dbclient.keys("account:*")
+cleanup_keys = Familia.dbclient.keys('account:*')
 Familia.dbclient.del(*cleanup_keys) if cleanup_keys.any?
 
 puts "\n🎉 Demo complete! The validation framework is ready for use."
-puts "    See try/validation/ for comprehensive test examples."
+puts '    See try/validation/ for comprehensive test examples.'

data/examples/{bit_encoding_integration.rb → permissions.rb}

@@ -17,11 +17,11 @@ class User < Familia::Horreum
   field :user_id
   field :email
   field :name
-  field :role  # admin, editor, viewer, guest
+  field :role # admin, editor, viewer, guest
   field :created_at
 
-  sorted_set :documents  # Documents this user can access
-  sorted_set :recent_activity  # Recent document access
+  sorted_set :documents # Documents this user can access
+  sorted_set :recent_activity # Recent document access
 end
 
 class Document < Familia::Horreum
@@ -39,10 +39,10 @@ class Document < Familia::Horreum
   field :content
   field :created_at
   field :updated_at
-  field :document_type  # public, private, confidential
+  field :document_type # public, private, confidential
 
-  sorted_set :collaborators  # Users with access to this document
-  list :audit_log  # Track permission changes and access
+  sorted_set :collaborators # Users with access to this document
+  list :audit_log # Track permission changes and access
 
   # Add document to user's collection with specific permissions
   def share_with_user(user, *permissions)
@@ -78,7 +78,7 @@ class Document < Familia::Horreum
 
   # Get users with specific permission level or higher
   def users_with_permission(*required_permissions)
-    all_permissions.select do |user_id, user_perms|
+    all_permissions.select do |_user_id, user_perms|
       required_permissions.all? { |perm| user_perms.include?(perm) }
     end.keys
   end
@@ -102,7 +102,7 @@ class Document < Familia::Horreum
       active_users: active_users,
       total_collaborators: collaborators.size,
       permission_breakdown: all_permissions,
-      audit_entries: audit_log.range(0, 50)
+      audit_entries: audit_log.range(0, 50),
     }
   end
 end
@@ -113,10 +113,10 @@ class DocumentService
   ROLE_PERMISSIONS = {
     guest: [:read],
     viewer: [:read],
-    commenter: [:read, :append],
-    editor: [:read, :write, :edit],
-    reviewer: [:read, :write, :edit, :delete],
-    admin: [:read, :write, :edit, :delete, :configure, :transfer, :admin]
+    commenter: %i[read append],
+    editor: %i[read write edit],
+    reviewer: %i[read write edit delete],
+    admin: %i[read write edit delete configure transfer admin],
   }.freeze
 
   def self.create_document(owner, title, content, doc_type = 'private')
@@ -164,7 +164,7 @@ class DocumentService
 
     documents.each do |doc|
       users.each do |user|
-        doc.revoke_access(user)  # Clear existing
+        doc.revoke_access(user) # Clear existing
         doc.share_with_user(user, *permissions) if permissions
       end
     end
@@ -173,8 +173,8 @@ end
 
 # Example Usage and Demonstration
 if __FILE__ == $0
-  puts "🚀 Familia Bit Encoding Integration Example"
-  puts "=" * 50
+  puts '🚀 Familia Bit Encoding Integration Example'
+  puts '=' * 50
 
   # Create users
   alice = User.new(user_id: 'alice', email: 'alice@company.com', name: 'Alice Smith', role: 'admin')
@@ -182,9 +182,9 @@ if __FILE__ == $0
   charlie = User.new(user_id: 'charlie', email: 'charlie@company.com', name: 'Charlie Brown', role: 'viewer')
 
   # Create documents
-  doc1 = DocumentService.create_document(alice, "Q4 Financial Report", "Confidential financial data...", 'confidential')
-  doc2 = DocumentService.create_document(alice, "Team Meeting Notes", "Weekly standup notes...", 'private')
-  doc3 = DocumentService.create_document(bob, "Project Proposal", "New feature proposal...", 'public')
+  doc1 = DocumentService.create_document(alice, 'Q4 Financial Report', 'Confidential financial data...', 'confidential')
+  doc2 = DocumentService.create_document(alice, 'Team Meeting Notes', 'Weekly standup notes...', 'private')
+  doc3 = DocumentService.create_document(bob, 'Project Proposal', 'New feature proposal...', 'public')
 
   # Share documents with different permission levels
   puts "\n📄 Document Sharing:"
@@ -209,14 +209,14 @@ if __FILE__ == $0
   analytics = doc1.access_analytics
   puts "Financial Report - Active Users: #{analytics[:active_users].size}"
   puts "Total Collaborators: #{analytics[:total_collaborators]}"
-  puts "Permission Breakdown:"
+  puts 'Permission Breakdown:'
   analytics[:permission_breakdown].each do |user_id, perms|
     puts "  #{user_id}: #{perms.join(', ')}"
   end
 
   # Demonstrate bit encoding efficiency
   puts "\n⚡ Bit Encoding Efficiency:"
-  score = Familia::Features::Relationships::ScoreEncoding.encode_score(Time.now, [:read, :write, :edit, :delete])
+  score = Familia::Features::Relationships::ScoreEncoding.encode_score(Time.now, %i[read write edit delete])
   decoded = Familia::Features::Relationships::ScoreEncoding.decode_score(score)
   puts "Encoded score: #{score}"
   puts "Decoded permissions: #{decoded[:permission_list].join(', ')}"
@@ -225,13 +225,16 @@ if __FILE__ == $0
   # Cleanup
   puts "\n🧹 Cleanup:"
   [alice, bob, charlie].each { |user| user.documents.clear }
-  [doc1, doc2, doc3].each { |doc| doc.clear_all_permissions; doc.collaborators.clear }
+  [doc1, doc2, doc3].each do |doc|
+    doc.clear_all_permissions
+    doc.collaborators.clear
+  end
 
-  puts "✅ Integration example completed successfully!"
+  puts '✅ Integration example completed successfully!'
   puts "\nThis demonstrates:"
-  puts "• Fine-grained permission management with 8-bit encoding"
-  puts "• Role-based access control with business logic"
-  puts "• Time-based analytics and audit trails"
-  puts "• Efficient Redis storage with sorted sets"
-  puts "• Production-ready error handling and validation"
+  puts '• Fine-grained permission management with 8-bit encoding'
+  puts '• Role-based access control with business logic'
+  puts '• Time-based analytics and audit trails'
+  puts '• Efficient Redis storage with sorted sets'
+  puts '• Production-ready error handling and validation'
 end