familia 2.0.0.pre18 → 2.0.0.pre21

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-pre19.md

@@ -0,0 +1,197 @@
+# Migrating Guide: v2.0.0-pre19
+
+This version introduces significant improvements to Familia's database operations, making them more atomic, reliable, and consistent with Rails conventions. The changes include enhanced error handling, optimistic locking support, and breaking API changes.
+
+## Breaking Changes
+
+### Management.create → create!
+
+**What Changed:**
+
+The `create` class method has been renamed to `create!` to follow Rails conventions and indicate that it raises exceptions on failure.
+
+**Before:**
+```ruby
+user = User.create(email: "test@example.com")
+```
+
+**After:**
+```ruby
+user = User.create!(email: "test@example.com")
+```
+
+**Why This Matters:**
+
+- Follows Rails naming conventions where `!` methods raise exceptions
+- Makes it clear that `CreationError` will be raised if object already exists
+- Prevents silent failures in object creation
+
+### save_if_not_exists → save_if_not_exists!
+
+**What Changed:**
+
+The `save_if_not_exists` method has been renamed to `save_if_not_exists!` and now includes optimistic locking with automatic retry logic.
+
+**Before:**
+```ruby
+success = user.save_if_not_exists
+```
+
+**After:**
+```ruby
+success = user.save_if_not_exists!
+```
+
+**Behavior Changes:**
+- Now uses Redis WATCH/MULTI/EXEC for optimistic locking
+- Automatically retries up to 3 times on `OptimisticLockError`
+- Raises `RecordExistsError` if object already exists
+- More atomic and thread-safe
+
+## Enhanced Error Handling
+
+### New Error Hierarchy
+
+**What's New:**
+
+A structured error hierarchy provides better error categorization:
+
+```ruby
+Familia::Problem                    # Base class
+├── Familia::PersistenceError       # Redis/database errors
+│   ├── Familia::NonUniqueKey
+│   ├── Familia::OptimisticLockError
+│   ├── Familia::OperationModeError
+│   ├── Familia::NoConnectionAvailable
+│   ├── Familia::NotFound
+│   └── Familia::NotConnected
+└── Familia::HorreumError           # Model-related errors
+    ├── Familia::CreationError
+    ├── Familia::NoIdentifier
+    ├── Familia::FieldTypeError
+    ├── Familia::AutoloadError
+    ├── Familia::SerializerError
+    ├── Familia::UnknownFieldError
+    └── Familia::NotDistinguishableError
+```
+
+**Migration:**
+
+Update exception handling to use specific error classes:
+
+```ruby
+# Before
+rescue Familia::Problem => e
+  # Handle all errors
+
+# After - More granular handling
+rescue Familia::CreationError => e
+  # Handle creation failures specifically
+rescue Familia::OptimisticLockError => e
+  # Handle concurrent modification
+rescue Familia::PersistenceError => e
+  # Handle database-related errors
+```
+
+### New Exception Types
+
+- **`CreationError`**: Raised when object creation fails (replaces generic errors)
+- **`OptimisticLockError`**: Raised when WATCH fails due to concurrent modification
+- **`UnknownFieldError`**: Raised when referencing non-existent fields
+
+## Database Operation Improvements
+
+### Atomic Save Operations
+
+**What Changed:**
+
+The `save` method now uses a single Redis transaction for complete atomicity:
+
+```ruby
+# All operations now happen atomically:
+# 1. Save all fields (HMSET)
+# 2. Set expiration (EXPIRE)
+# 3. Update indexes
+# 4. Add to instances collection
+```
+
+**Benefits:**
+- Eliminates race conditions during save operations
+- Ensures data consistency across related operations
+- Better performance with fewer round trips
+
+### Enhanced Timestamp Precision
+
+**What Changed:**
+
+Created/updated timestamps now use float values instead of integers for higher precision:
+
+**Before:**
+```ruby
+user.created  # => 1697234567 (integer seconds)
+```
+
+**After:**
+```ruby
+user.created  # => 1697234567.123 (float with milliseconds)
+```
+
+**Migration:**
+
+No code changes needed. Existing integer timestamps continue to work.
+
+## Redis Command Enhancements
+
+### New Commands Available
+
+Added support for optimistic locking commands:
+- `watch(key)` - Watch key for changes
+- `unwatch()` - Remove all watches
+- `discard()` - Discard queued commands
+
+### Improved Command Logging
+
+Database command logging now includes:
+- Structured format for better readability
+- Pipelined operation tracking
+- Transaction boundary markers
+- Command timing information
+
+## Terminology Updates
+
+**What Changed:**
+
+Standardized on "pipelined" terminology throughout (previously mixed "pipeline"/"pipelined").
+
+**Files Affected:**
+- Method names now consistently use "pipelined"
+- Documentation updated to match Redis terminology
+- Log messages standardized
+
+**Migration:**
+
+No code changes needed - this was an internal consistency improvement.
+
+## Recommended Actions
+
+1. **Update method calls:**
+   ```ruby
+   # Replace all instances
+   Model.create(...)      → Model.create!(...)
+   obj.save_if_not_exists → obj.save_if_not_exists!
+   ```
+
+2. **Review error handling:**
+   ```ruby
+   # Consider more specific error handling
+   rescue Familia::CreationError
+   rescue Familia::OptimisticLockError
+   ```
+
+3. **Test concurrent operations:**
+   - The new optimistic locking provides better concurrency handling
+   - Verify your application handles `OptimisticLockError` appropriately
+
+4. **Review logging:**
+   - Enhanced database command logging may affect log volume
+   - Adjust log levels if needed for production environments

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
 ```