familia 2.0.0.pre19 → 2.0.0.pre22

data/docs/guides/thread-safety-monitoring.md

@@ -0,0 +1,61 @@
+Thread Safety Monitoring Usage Guide
+
+### Development
+```ruby
+# Enable monitoring during local testing
+Familia.start_monitoring!
+# ... run your application ...
+report = Familia.thread_safety_report
+puts report[:hot_spots]  # See which mutexes are contentious
+puts report[:recommendations]  # Get actionable insights
+```
+
+### CI/CD
+```bash
+# Add to test pipeline for race condition detection
+FAMILIA_THREAD_SAFETY=1 bundle exec rspec
+# Check for any race detections in CI logs
+```
+
+```ruby
+# In test setup
+if ENV['FAMILIA_THREAD_SAFETY']
+  Familia.start_monitoring!
+  at_exit do
+    report = Familia.thread_safety_report
+    if report[:summary][:race_detections] > 0
+      puts "❌ Race conditions detected: #{report[:summary][:race_detections]}"
+      exit 1
+    end
+  end
+end
+```
+
+### Production
+**APM Integration:**
+```ruby
+# Export metrics to DataDog, NewRelic, etc.
+Thread.new do
+  loop do
+    metrics = Familia.thread_safety_metrics
+    StatsD.gauge('familia.thread_safety.health_score', metrics['familia.thread_safety.health_score'])
+    StatsD.count('familia.thread_safety.contentions', metrics['familia.thread_safety.mutex_contentions'])
+    sleep 60
+  end
+end
+```
+
+**Health Check Endpoint:**
+```ruby
+# In Rails routes or Sinatra
+get '/health/thread_safety' do
+  report = Familia.thread_safety_report
+  status = report[:health] >= 80 ? 200 : 503
+  json report
+end
+```
+
+**Key Alerts:**
+- `health_score < 70` → Investigate contention
+- `race_detections > 0` → Critical issue
+- `avg_wait_ms > 100` → Performance problem

data/docs/guides/{time-utilities.md → time-literals.md}

@@ -9,8 +9,8 @@ The `Familia::Refinements::TimeLiterals` module extends Ruby's built-in classes
 ```ruby
 using Familia::Refinements::TimeLiterals
 
-2.hours        #=> 7200 (seconds)
-"30m".in_seconds  #=> 1800
+2.hours        #=> 7200.0 (seconds)
+"30m".in_seconds  #=> 1800.0
 timestamp.days_old  #=> 5.2
 ```
 
@@ -45,12 +45,12 @@ using Familia::Refinements::TimeLiterals
 # Singular and plural forms work identically
 1.second   #=> 1
 30.seconds #=> 30
-5.minutes  #=> 300
-2.hours    #=> 7200
-3.days     #=> 259200
-1.week     #=> 604800
-2.months   #=> 5259492
-1.year     #=> 31556952
+5.minutes  #=> 300.0
+2.hours    #=> 7200.0
+3.days     #=> 259200.0
+1.week     #=> 604800.0
+2.months   #=> 5259492.0
+1.year     #=> 31556952.0
 ```
 
 ### Converting Time Units Back
@@ -80,9 +80,9 @@ Parse human-readable time strings:
 
 | Unit | Abbreviations | Example |
 |------|---------------|---------|
-| Microseconds | `us`, `μs`, `microsecond`, `microseconds` | `"500us"` |
+| Microseconds | `us`, `μs`, `microsecond`, `microseconds` | `"500μs"` |
 | Milliseconds | `ms`, `millisecond`, `milliseconds` | `"250ms"` |
-| Seconds | `s`, `second`, `seconds` | `"30s"` |
+| Seconds | (no unit) | `"30"` |
 | Minutes | `m`, `minute`, `minutes` | `"15m"` |
 | Hours | `h`, `hour`, `hours` | `"2h"` |
 | Days | `d`, `day`, `days` | `"7d"` |
@@ -90,7 +90,7 @@ Parse human-readable time strings:
 | Months | `mo`, `month`, `months` | `"6mo"` |
 | Years | `y`, `year`, `years` | `"1y"` |
 
-**Note**: Use `"mo"` for months to avoid confusion with `"m"` (minutes).
+**Note**: Use `"mo"` for months to avoid confusion with `"m"` (minutes). Seconds don't require a unit suffix.
 
 ## Age Calculations
 
@@ -215,7 +215,7 @@ If upgrading from earlier versions:
 12.months != 1.year  # Different values
 
 # New behavior (consistent)
-12.months == 1.year  # Same value: 31,556,952 seconds
+12.months == 1.year  # Same value: 31,556,952.0 seconds
 ```
 
 Update any code that relied on the old 365-day year constant to expect the new Gregorian year values.

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

@@ -0,0 +1,241 @@
+# Migrating Guide: v2.0.0-pre22
+
+This version introduces significant performance optimizations for Redis operations, completes the bidirectional relationships feature, and improves flexibility for external identifiers.
+
+## Major Features
+
+### Bidirectional Relationship Methods
+
+**What's New:**
+
+The `participates_in` declarations now generate reverse collection methods with the `_instances` suffix, providing symmetric access to relationships from both directions.
+
+**Generated Methods:**
+```ruby
+class User < Familia::Horreum
+  participates_in Team, :members
+  participates_in Organization, :employees
+end
+
+# New reverse collection methods:
+user.team_instances         # => [team1, team2]
+user.team_ids               # => ["team_123", "team_456"]
+user.team?                  # => true/false
+user.team_count             # => 2
+
+user.organization_instances # => [org1]
+user.organization_ids       # => ["org_789"]
+```
+
+**Custom Names:**
+```ruby
+class User < Familia::Horreum
+  participates_in Organization, :contractors, as: :clients
+end
+
+user.clients_instances      # Instead of organization_instances
+user.clients_ids            # Instead of organization_ids
+```
+
+**Migration:**
+
+No changes required for existing code. The new methods are additive and don't affect existing `participates_in` functionality.
+
+### Pipelined Bulk Loading
+
+**What's New:**
+
+New `load_multi` methods provide up to 2× performance improvement for bulk object loading by using Redis pipelining.
+
+**Before (N×2 commands):**
+```ruby
+users = ids.map { |id| User.find_by_id(id) }
+# For 14 objects: 28 Redis commands (14 EXISTS + 14 HGETALL)
+```
+
+**After (1 round trip):**
+```ruby
+users = User.load_multi(ids)
+# For 14 objects: 1 pipelined batch with 14 HGETALL commands
+```
+
+**Additional Methods:**
+```ruby
+# Load by full dbkeys
+users = User.load_multi_by_keys(['user:123:object', 'user:456:object'])
+
+# Filter out nils for missing objects
+existing_only = User.load_multi(ids).compact
+```
+
+### Optional EXISTS Check Optimization
+
+**What's New:**
+
+The `find_by_id` and related methods now support skipping the EXISTS check for 50% reduction in Redis commands.
+
+```ruby
+# Default behavior (unchanged, 2 commands)
+user = User.find_by_id(123)
+
+# Optimized mode (1 command)
+user = User.find_by_id(123, check_exists: false)
+```
+
+**When to Use:**
+- Performance-critical paths
+- Bulk operations with known-to-exist keys
+- High-throughput APIs
+- Loading from sorted set results
+
+## Enhanced Features
+
+### Flexible External Identifier Format
+
+**What's New:**
+
+The `external_identifier` feature now supports custom format templates.
+
+**Examples:**
+```ruby
+# Default format (unchanged)
+class User < Familia::Horreum
+  feature :external_identifier
+end
+user.extid  # => "ext_abc123def456"
+
+# Custom prefix
+class Customer < Familia::Horreum
+  feature :external_identifier, format: 'cust_%{id}'
+end
+customer.extid  # => "cust_abc123def456"
+
+# Different separator
+class APIKey < Familia::Horreum
+  feature :external_identifier, format: 'api-%{id}'
+end
+key.extid  # => "api-abc123def456"
+```
+
+### Atomic Index Rebuilding
+
+**What's New:**
+
+Auto-generated rebuild methods for all unique and multi indexes with zero downtime.
+
+**Examples:**
+
+```ruby
+# Class-level unique index
+User.rebuild_email_lookup
+
+# Instance-scoped unique index
+company.rebuild_badge_index
+
+# With progress tracking
+User.rebuild_email_lookup(batch_size: 100) do |progress|
+  puts "#{progress[:completed]}/#{progress[:total]}"
+end
+```
+
+When to Use:
+- After data migrations or bulk imports
+- Recovering from index corruption
+- Adding indexes to existing data
+
+Migration:
+
+Run rebuild methods once after upgrade to ensure index consistency. No code changes required—methods are auto-generated from existing
+unique_index and multi_index declarations.
+
+
+## Bug Fixes
+
+### Symbol/String Target Classes in participates_in
+
+**What Was Fixed:**
+
+Fixed multiple bugs when using Symbol or String class names in `participates_in`:
+
+```ruby
+class Domain < Familia::Horreum
+  # All forms now work correctly:
+  participates_in Customer, :domains     # Class object
+  participates_in :Customer, :domains    # Symbol (was broken)
+  participates_in 'Customer', :domains   # String (was broken)
+end
+```
+
+**Errors Fixed:**
+- `NoMethodError: private method 'member_by_config_name'`
+- `NoMethodError: undefined method 'familia_name' for Symbol`
+- `NoMethodError: undefined method 'config_name' for Symbol`
+- Confusing nil errors for unloaded classes
+
+**New Behavior:**
+
+When a target class can't be resolved, you now get a helpful error:
+```
+Target class 'Customer' could not be resolved.
+Possible causes:
+1. The class hasn't been loaded yet (load order issue)
+2. The class name is misspelled
+3. The class doesn't inherit from Familia::Horreum
+
+Registered Familia classes: ["User", "Team", "Organization"]
+```
+
+## Performance Recommendations
+
+### Use Bulk Loading for Collections
+
+```ruby
+# ❌ Avoid N+1 queries
+team.members.to_a.map { |id| User.find_by_id(id) }
+
+# ✅ Use bulk loading
+User.load_multi(team.members.to_a)
+```
+
+### Skip EXISTS Checks When Safe
+
+```ruby
+# When loading from sorted sets (keys guaranteed to exist)
+task_ids = project.tasks.range(0, 9)
+tasks = Task.load_multi(task_ids)  # Or use check_exists: false
+
+# For known-existing keys
+user = User.find_by_id(session[:user_id], check_exists: false)
+```
+
+### Leverage Reverse Collection Methods
+
+```ruby
+# ❌ Manual parsing of participations
+team_keys = user.participations.members.select { |k| k.start_with?("team:") }
+team_ids = team_keys.map { |k| k.split(':')[1] }
+teams = Team.load_multi(team_ids)
+
+# ✅ Use generated methods
+teams = user.team_instances
+```
+
+## Backwards Compatibility
+
+All changes in this version are backwards compatible:
+
+- New methods are additive and don't affect existing APIs
+- Default behaviors remain unchanged
+- Symbol/String fixes don't require code changes
+
+## Recommended Actions
+
+1. **Adopt bulk loading** for performance-critical paths
+2. **Use reverse collection methods** to simplify relationship queries
+3. **Consider check_exists: false** for guaranteed-existing keys
+4. **Update external_identifier formats** if custom prefixes are needed
+
+## See Also
+
+- [Relationships Guide](../guides/feature-relationships.md)
+- [Performance Optimization Guide](../guides/optimized-loading.md)

data/docs/overview.md

@@ -289,13 +289,11 @@ class SecureModel < Familia::Horreum
   # → password, password= (no fast writer method)
   # → Values wrapped in RedactedString
 
-  # Redacted fields are persisted but return [REDACTED] in logs
-  redacted_field :security_question
-  # → security_question, security_question=, security_question!
+  # Note: All transient field values are automatically wrapped in RedactedString
+  # for security - they never persist to the database
 
-  # Object identifier fields auto-generate unique IDs
+  # Object identifier fields auto-generate unique IDs when using the feature
   # → objid, objid= (lazy generation, preserves initialization values)
-  # → objid_generator_used (provenance tracking)
 end
 
 # Usage examples
@@ -856,7 +854,7 @@ Familia.debug = true  # Shows feature loading sequence
 Familia.debug = true
 
 # Check what's in Valkey
-Familia.redis.keys('*')  # List all keys (use carefully in production)
+Familia.dbclient.keys('*')  # List all keys (use carefully in production)
 ```
 
 ## Testing
@@ -880,7 +878,7 @@ Familia.config.current_key_version = :v1
 
 # Clear data between tests
 def clear_redis
-  Familia.redis.flushdb
+  Familia.dbclient.flushdb
 end
 
 # Feature-specific testing patterns
@@ -898,8 +896,8 @@ end
 
 def test_relationships_cleanup
   # Clean up relationship indexes
-  Familia.redis.keys('*:relationships:*').each do |key|
-    Familia.redis.del(key)
+  Familia.dbclient.keys('*:relationships:*').each do |key|
+    Familia.dbclient.del(key)
   end
 end
 ```