familia 2.0.0.pre17 → 2.0.0.pre19

data/docs/guides/core-field-system.md

@@ -50,17 +50,20 @@ customer.email = "admin@acme.com"     # Custom method name
 customer.name!("Updated Corp")        # Fast writer (immediate DB persistence)
 ```
 
-### Field Categories
+### Special Field Types
 
-Fields can be categorized for special processing by features:
+Use dedicated field methods provided by features for special field behaviors:
 
 ```ruby
 class Document < Familia::Horreum
-  field :title                           # Regular field
-  field :content, category: :encrypted   # Will be processed by encrypted_fields feature
-  field :api_key, category: :transient   # Non-persistent field
-  field :tags, category: :indexed        # Custom category for indexing
-  field :metadata, category: :json       # Custom JSON serialization
+  feature :encrypted_fields
+  feature :transient_fields
+
+  field :title                    # Regular persistent field
+  encrypted_field :content        # Encrypted storage
+  transient_field :api_key        # Non-persistent (memory only)
+  field :tags                     # Regular field
+  field :metadata                 # Regular field
 end
 ```
 
@@ -285,27 +288,28 @@ order.priority_urgent?   # => false
 
 ```ruby
 class Product < Familia::Horreum
-  field :name, category: :searchable
-  field :price, category: :numeric
-  field :description, category: :text
-  field :secret_key, category: :encrypted
+  feature :transient_fields
+
+  field :name
+  field :price
+  field :description
   transient_field :temp_data
 end
 
 # Get all field names
 Product.fields
-# => [:name, :price, :description, :secret_key, :temp_data]
+# => [:name, :price, :description, :temp_data]
 
 # Get field types registry
 Product.field_types
 # => { name: #<FieldType...>, price: #<FieldType...>, ... }
 
-# Get fields by category
-Product.fields.select { |f| Product.field_types[f].category == :searchable }
-# => [:name]
+# Get fields by category (read-only introspection)
+Product.fields.select { |f| Product.field_types[f].category == :transient }
+# => [:temp_data]
 
 # Get persistent vs transient fields
-Product.persistent_fields  # => [:name, :price, :description, :secret_key]
+Product.persistent_fields  # => [:name, :price, :description]
 Product.transient_fields   # => [:temp_data]
 
 # Field method mapping (for backward compatibility)
@@ -313,15 +317,24 @@ Product.field_method_map
 # => { name: :name, price: :price, secret_key: :secret_key, temp_data: :temp_data }
 ```
 
-### Field Categories for Feature Processing
+### Using Field Type Category for Introspection
+
+The `category` method on FieldType provides read-only metadata for introspection:
 
 ```ruby
-# Features can process fields by category
+# Custom field type with category metadata
+class SearchableFieldType < Familia::FieldType
+  def category
+    :searchable
+  end
+end
+
+# Features can process fields by inspecting their category
 module SearchableFieldsFeature
   def self.included(base)
     base.extend ClassMethods
 
-    # Process all searchable fields
+    # Find all searchable fields by inspecting field type category
     searchable_fields = base.fields.select do |field|
       base.field_types[field].category == :searchable
     end
@@ -348,11 +361,17 @@ module SearchableFieldsFeature
 end
 
 class Product < Familia::Horreum
-  feature :searchable_fields  # Processes all :searchable category fields
+  feature :searchable_fields
 
-  field :name, category: :searchable
-  field :description, category: :searchable
-  field :internal_id, category: :system
+  # Use custom field type with searchable category
+  def self.searchable_field(name, **options)
+    field_type = SearchableFieldType.new(name, **options)
+    register_field_type(field_type)
+  end
+
+  searchable_field :name
+  searchable_field :description
+  field :internal_id
 end
 
 # Auto-generated search methods available
@@ -733,10 +752,13 @@ end
 ### 1. Choose Appropriate Field Types
 
 ```ruby
-# Use built-in field types when possible
+# Use dedicated field methods provided by features
 class User < Familia::Horreum
-  field :name                    # Simple string field
-  field :metadata, category: :json  # For complex data
+  feature :transient_fields
+  feature :encrypted_fields
+
+  field :name                    # Simple persistent field
+  field :metadata                # For complex data
   transient_field :temp_token    # For runtime-only data
   encrypted_field :api_key       # For sensitive data
 end

data/docs/guides/feature-expiration.md

@@ -66,7 +66,7 @@ session.default_expiration  # => 900.0
 session.update_expiration  # Uses instance expiration (15 minutes)
 
 # Or specify expiration inline
-session.update_expiration(default_expiration: 5.minutes)
+session.update_expiration(expiration: 5.minutes)
 ```
 
 ## Advanced Usage
@@ -112,7 +112,7 @@ customer = Customer.new(customer_id: 'cust_123')
 customer.save
 
 # This will set TTL on the main object AND all related fields
-customer.update_expiration(default_expiration: 12.hours)
+customer.update_expiration(expiration: 12.hours)
 # Sets expiration on:
 # - customer:cust_123 (main hash)
 # - customer:cust_123:recent_orders (list)
@@ -137,9 +137,9 @@ class AnalyticsEvent < Familia::Horreum
     save
 
     if should_expire?
-      update_expiration(default_expiration: 1.hour)
+      update_expiration(expiration: 1.hour)
     else
-      update_expiration(default_expiration: 30.days)
+      update_expiration(expiration: 30.days)
     end
   end
 end
@@ -200,7 +200,7 @@ class SessionCleanupJob
     # Extend expiration for active sessions
     UserSession.all.each do |session|
       if session.recently_active?
-        session.update_expiration(default_expiration: 30.minutes)
+        session.update_expiration(expiration: 30.minutes)
       end
     end
   end
@@ -225,7 +225,7 @@ class SessionExpirationMiddleware
       session = UserSession.find(session_token)
 
       # Extend session TTL on each request
-      session&.update_expiration(default_expiration: 30.minutes)
+      session&.update_expiration(expiration: 30.minutes)
     end
 
     @app.call(env)
@@ -268,14 +268,14 @@ end
 class SessionManager
   def self.extend_all_sessions(new_ttl)
     UserSession.all.each do |session|
-      session.update_expiration(default_expiration: new_ttl)
+      session.update_expiration(expiration: new_ttl)
     end
   end
 
   def self.expire_inactive_sessions
     UserSession.all.select(&:inactive?).each do |session|
       # Set very short TTL for inactive sessions
-      session.update_expiration(default_expiration: 5.minutes)
+      session.update_expiration(expiration: 5.minutes)
     end
   end
 
@@ -306,7 +306,7 @@ class DataRetentionService
       model_class = data_type.to_s.pascalize.constantize
 
       model_class.all.each do |record|
-        record.update_expiration(default_expiration: ttl)
+        record.update_expiration(expiration: ttl)
       end
     end
   end
@@ -323,7 +323,7 @@ DataRetentionService.apply_retention_policies
 ```ruby
 # ❌ Inefficient: Multiple round trips
 sessions.each do |session|
-  session.update_expiration(default_expiration: 1.hour)
+  session.update_expiration(expiration: 1.hour)
 end
 
 # ✅ Efficient: Batch operations
@@ -357,7 +357,7 @@ class ResilientSession < Familia::Horreum
     return unless exists?
 
     begin
-      update_expiration(default_expiration: new_ttl)
+      update_expiration(expiration: new_ttl)
     rescue => e
       # Log error but don't crash the application
       Familia.logger.warn "Failed to update expiration for #{dbkey}: #{e.message}"
@@ -377,7 +377,7 @@ Familia.debug = true
 
 session = UserSession.new(session_token: 'debug_session')
 session.save
-session.update_expiration(default_expiration: 5.minutes)
+session.update_expiration(expiration: 5.minutes)
 # Logs will show:
 # [update_expiration] Expires session:debug_session in 300.0 seconds
 ```
@@ -388,11 +388,11 @@ session.update_expiration(default_expiration: 5.minutes)
 ```ruby
 session = UserSession.new
 # ❌ Won't work - object must be saved first
-session.update_expiration(default_expiration: 1.hour)
+session.update_expiration(expiration: 1.hour)
 
 # ✅ Correct - save first, then expire
 session.save
-session.update_expiration(default_expiration: 1.hour)
+session.update_expiration(expiration: 1.hour)
 ```
 
 **2. Related Fields Not Expiring**
@@ -459,7 +459,7 @@ RSpec.describe UserSession do
 
     it "applies TTL to database key" do
       session.save
-      session.update_expiration(default_expiration: 10.minutes)
+      session.update_expiration(expiration: 10.minutes)
 
       ttl = session.ttl
       expect(ttl).to be > 500  # Should be close to 600 seconds
@@ -470,7 +470,7 @@ RSpec.describe UserSession do
       session.save
       session.activity_log.push('login')  # Assume activity_log is a list
 
-      session.update_expiration(default_expiration: 5.minutes)
+      session.update_expiration(expiration: 5.minutes)
 
       # Both main object and related fields should have TTL
       expect(session.ttl).to be > 250
@@ -542,7 +542,7 @@ class TTLHealthCheck
         expired_count += 1
       elsif ttl < 300  # Less than 5 minutes remaining
         # Extend TTL for active sessions
-        session.update_expiration(default_expiration: 30.minutes) if session.active?
+        session.update_expiration(expiration: 30.minutes) if session.active?
       end
     end
 
@@ -565,7 +565,7 @@ class RobustSessionManager
     # Check if session exists and hasn't expired
     if session&.ttl&.positive?
       # Extend TTL on access
-      session.update_expiration(default_expiration: 30.minutes)
+      session.update_expiration(expiration: 30.minutes)
       session
     else
       # Create new session if old one expired

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

@@ -0,0 +1,58 @@
+# Migrating Guide: v2.0.0-pre18
+
+This version completes the JSON serialization implementation by removing the string-as-is optimization and fixes encrypted field visibility in serialization.
+
+## JSON Serialization for All Types
+
+**What Changed:**
+
+All field values (including strings) are now JSON-encoded during storage for consistent type preservation.
+
+**Storage Format:**
+
+```ruby
+# Before (v2.0.0-pre14):
+HGET user:123 name
+"John Doe"                    # Plain string
+
+# After (v2.0.0-pre18):
+HGET user:123 name
+"\"John Doe\""                # JSON-encoded string
+```
+
+**Migration:**
+
+No migration needed. The deserializer automatically handles:
+- **New format**: `"\"value\""` → `"value"`
+- **Legacy format**: `"value"` → `"value"`
+
+**Why This Matters:**
+
+Prevents data corruption for edge cases:
+- Badge `"007"` stays `"007"` (not converted to integer `7`)
+- String `"true"` stays `"true"` (not converted to boolean)
+- String `"null"` stays `"null"` (not converted to `nil`)
+
+## Encrypted Field Security Fix
+
+**What Changed:**
+
+Fields defined with `category: :encrypted` now correctly exclude encrypted data from `to_h()` output.
+
+**Before:**
+```ruby
+field :secret, category: :encrypted
+user.to_h  # => {"id" => "123", "secret" => {...}}  # ❌ Exposed!
+```
+
+**After:**
+```ruby
+field :secret, category: :encrypted
+user.to_h  # => {"id" => "123"}  # ✅ Secure
+```
+
+Both `encrypted_field` and `field :name, category: :encrypted` now behave identically for security.
+
+**Migration:**
+
+No code changes needed. Review any code relying on encrypted fields appearing in `to_h()` output.

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/qodo-merge-compliance.md

@@ -0,0 +1,96 @@
+# Qodo Merge Compliance Configuration
+
+This document describes the Qodo Merge (formerly PR-Agent) configuration for the Familia project.
+
+## Overview
+
+Qodo Merge provides automated PR analysis, code reviews, and compliance checks. Our configuration enables two key compliance features:
+
+1. **Codebase Duplication Compliance** - Uses RAG (Retrieval-Augmented Generation) to check for duplicate code across related repositories
+2. **Custom Compliance** - Project-specific rules tailored to Familia's development practices
+
+## Configuration Files
+
+### pr_agent.toml
+
+The main Qodo Merge configuration file located in the repository root. It includes:
+
+- **Response Language**: Set to English for consistency
+- **RAG Context Enrichment**: Enabled with related repositories (`delano/familia`, `delano/tryouts`, `delano/otto`)
+- **Custom Compliance Path**: References our custom compliance checklist
+- **Ignore Rules**: Excludes generated files and build artifacts from analysis
+
+### pr_compliance_checklist.yaml
+
+Custom compliance rules specific to Familia development:
+
+#### ErrorHandling
+All external API calls and database operations must have proper error handling with try-catch blocks or appropriate error handling mechanisms.
+
+#### TestCoverage
+New features must include tests using the Tryouts framework. Test files should be in the `try/` directory following the `*_try.rb` or `*.try.rb` naming convention.
+
+#### ChangelogFragment
+User-facing changes must include a changelog fragment in the `changelog.d/` directory following RST format, or provide explicit justification for omission.
+
+#### DocumentationUpdates
+API changes must be reflected in documentation, including YARD comments for new public methods or updates to the `docs/` directory.
+
+#### BackwardCompatibility
+Changes must maintain backward compatibility or document breaking changes in migration guides with deprecation warnings.
+
+#### ThreadSafety
+Code handling shared state must be thread-safe with proper synchronization or clear documentation of thread-safety assumptions.
+
+#### DatabaseKeyNaming
+Database key generation must follow Familia conventions:
+- Use the configured `delim` separator (default `:`)
+- Avoid reserved keywords: `ttl`, `db`, `valkey`, `redis`
+- Handle empty identifiers to prevent stack overflow
+
+## Interactive Commands
+
+Team members can trigger on-demand Qodo Merge analysis in PR comments:
+
+- `/analyze --review` - Run code review
+- `/analyze --test` - Generate test suggestions
+- `/improve` - Get improvement suggestions
+- `/ask` - Ask questions about the PR
+
+## Compliance Status
+
+In PR comments from `@qodo-merge-pro`, you'll see:
+
+- 🟢 Green circle - Compliance check passed
+- 🔴 Red circle - Compliance check failed with details
+- ⚪ White circle - Compliance check not configured (should not appear with proper configuration)
+
+## References
+
+- [Qodo Merge Configuration Options](https://qodo-merge-docs.qodo.ai/usage-guide/configuration_options/)
+- [RAG Context Enrichment Guide](https://qodo-merge-docs.qodo.ai/core-abilities/rag_context_enrichment/)
+- [Compliance Guide](https://qodo-merge-docs.qodo.ai/tools/compliance/)
+- [Best Practices](https://docs.qodo.ai/qodo-documentation/qodo-merge/features/best-practices)
+
+## Maintenance
+
+### Updating Compliance Rules
+
+To add or modify compliance rules:
+
+1. Edit `pr_compliance_checklist.yaml`
+2. Ensure YAML syntax is valid: `ruby -r yaml -e "YAML.load_file('pr_compliance_checklist.yaml')"`
+3. Commit changes - they take effect immediately on new PRs
+
+### Updating Ignore Rules
+
+To exclude additional files from analysis:
+
+1. Edit the `[ignore]` section in `pr_agent.toml`
+2. Use glob patterns to match file paths
+3. Test with new PRs to verify exclusions work as expected
+
+## Future Improvements (Optional)
+
+- **Centralized Configuration**: Create a `pr-agent-settings` repository with `metadata.yaml` to share configuration across all repos
+- **Wiki Configuration**: Enable repo wiki and create `.pr_agent.toml` page (wiki config takes precedence over local files)